Skip to main content
Version: 2.0.0

Moveo.AI

Introduction

Welcome to the Moveo API. The API allows you to create Virtual Assistants and connect them with different channels such as Facebook, Viber, Web Widget as well as talk to any backend or external service. The API is designed according to REST principles. It uses JSON in request bodies and requires that the content-type: application/json header be specified for all such requests. The API will always respond with an object. Depending on context, resources may be returned as single objects or as arrays of objects, nested within the response object.

API Path Versioning​

The API paths are versioned. The current and latest version for API paths is v1, as seen in https://api.moveo.ai/api/v1/....

Account Slug​

Most API requests require an account_slug query parameter. This slug identifies your specific Moveo.AI account. You can typically find your account slug within your Moveo.AI dashboard or from your account administrator. Ensure this parameter is included in your requests where specified.

API Host​

Moveo is available in the following regions. The API host is specific to the region.

Authorization​

Moveo supports two primary authentication methods:

  1. API Keys: These are static keys provided to you for server-to-server authentication.
  2. JSON Web Tokens (JWTs): These are typically used for user-delegated authentication.

You should include your authentication credential in the Authorization header. - For JWTs, use the Bearer scheme: Authorization: Bearer <YOUR_JWT_TOKEN> - For API Keys, use the following scheme: Authorization: apikey <YOUR_API_KEY>

API Key Types​

When creating an API key, you must select one of the following types which determines the scope of access:

  • manage: For management operations. Grants access to endpoints under brains, broadcasts, campaigns, collections, desks, plugins, and roles.
  • use: For sending messages only. Restricted to session, message, and classify endpoints.
  • analytics: For reading analytics data through the Analytics GraphQL API. It grants no access to the endpoints in this reference. Each endpoint in this documentation specifies which API key type(s) it supports.

Pagination​

All paginated endpoints support cursor-based pagination.

Cursor-based pagination is a common pagination strategy that avoids many of the pitfalls of offset–limit pagination. It works by returning a pointer to a specific item in the dataset. On subsequent requests, the server returns results after the given pointer.

The default page size is 100 objects. To use a different page size, use the limit query parameter. To change the attribute by which results are sorted, use the sort query parameter. Each endpoint supports different sorting attributes.

Total Count Information​

By default, paginated responses do not include the total count of all items for performance reasons. To include the total count in the pagination response, add verbose=true as a query parameter. When enabled, the pagination object will include a total field with the complete count of all items matching the query filters. Example: - GET /v1/desks/{desk_id}/brains?limit=10 - Returns pagination without total - GET /v1/desks/{desk_id}/brains?limit=10&verbose=true - Returns pagination with total count

Rate Limits​

Moveo APIs are subject to rate limiting. If the rate limit is exceeded Moveo may return a 429 Too Many Requests HTTP status code. We apply rate limits to prevent abuse, spam, denial-of-service attacks, and similar issues. Our goal is to keep the limits high enough so that any application using Moveo as intended will not encounter them.

To help manage your API calls, the following headers are typically returned with each API response:

  • X-RateLimit-Limit: The maximum number of requests allowed in the current time window.
  • X-RateLimit-Remaining: The number of requests remaining in the current time window.
  • X-RateLimit-Reset: The time (in UTC epoch seconds) when the current window resets.

When calling the Moveo API, you should implement 429 retry logic using exponential backoff and jitter.

Request Size Limits​

The Moveo API imposes a 10mb request size limit on HTTPS.

Errors​

Moveo uses standard HTTP status codes to communicate errors. In general, a 2xx status code indicates success while 4xx indicates an error, in which case, the response body includes a JSON object with a code, message, and extra field containing more details. Multiple errors can only be included in a 400 Bad Request. A 5xx status code indicates that something went wrong on our end.

Example Error Response:

 {
  "code": "unauthorized",
  "message": "No authorization token was found",
  "extra": {}
 }

Common Error Codes:

  • unauthorized: Authentication credentials missing or invalid.
  • permission_denied: Authenticated user lacks permission for the action.
  • validation_error: Request input failed validation. extra field often contains details.
  • resource_not_found: The requested resource does not exist.
  • invalid_request: General request format issue.

Authentication​

JWT token for authentication

Security Scheme Type:

http

HTTP Authorization Scheme:

bearer

Bearer format:

JWT

Contact

Moveo.AI Support: support@moveo.ai

URL: https://moveo.ai

Last updated on