Ask the AI about your data

Answers in natural language a question about the data of your account, optionally also searching the web.

POST

/api/v1/ai/ask

curl https://app.filmo.io/api/v1/ai/ask \
  --request POST \
  --header "Authorization: Bearer $FILMO_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{
  "question": "¿Qué pedidos tengo confirmados la semana que viene y qué material sale en ellos?",
  "webSearch": false,
  "mode": "instant"
}'

Node.jsfetch('https://app.filmo.io/api/v1/ai/ask', { method: 'POST', headers: { Authorization: 'Bearer YOUR_FILMO_API_KEY', 'Content-Type': 'application/json' }, body: JSON.stringify({ question: '¿Qué pedidos tengo confirmados la semana que viene y qué material sale en ellos?', webSearch: false, mode: 'instant' }) })Pythonimport requests requests.post("https://app.filmo.io/api/v1/ai/ask", headers={ "Authorization": "Bearer YOUR_FILMO_API_KEY", "Content-Type": "application/json" }, json={ "question": "¿Qué pedidos tengo confirmados la semana que viene y qué material sale en ellos?", "webSearch": False, "mode": "instant" } )

{
  "data": {
    "answer": "Example answer",
    "needsMoreContext": true,
    "webSearchSources": [
      {
        "url": "https://example.com/resource",
        "title": "Example title",
        "favicon": "Example favicon"
      }
    ]
  }
}

{
  "type": "https://docs.filmo.io/errors/validation_error",
  "title": "Validation error",
  "status": 400,
  "code": "validation_error",
  "detail": "2 validation errors",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "errors": [
    {
      "path": "name",
      "code": "too_small",
      "message": "Must be at least 1 characters long"
    },
    {
      "path": "contactType",
      "code": "invalid_value",
      "message": "Value not allowed; expected company, person"
    }
  ]
}

{
  "type": "https://docs.filmo.io/errors/unauthorized",
  "title": "Unauthorized",
  "status": 401,
  "code": "unauthorized",
  "detail": "Missing Authorization header: Bearer <api key>",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c"
}

{
  "type": "https://docs.filmo.io/errors/addon_required",
  "title": "Add-on required",
  "status": 402,
  "code": "addon_required",
  "detail": "Your plan does not include the add-on this operation requires",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c"
}

{
  "type": "https://docs.filmo.io/errors/insufficient_scope",
  "title": "Insufficient scope",
  "status": 403,
  "code": "insufficient_scope",
  "detail": "The API key does not have the required scope (orders:write)",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "requiredScope": "ai:ask"
}

{
  "type": "https://docs.filmo.io/errors/not_found",
  "title": "Not found",
  "status": 404,
  "code": "not_found",
  "detail": "Resource not found",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c"
}

{
  "type": "https://docs.filmo.io/errors/conflict",
  "title": "Conflict",
  "status": 409,
  "code": "conflict",
  "detail": "The current state of the resource does not allow the operation",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "errors": [
    {
      "path": "",
      "code": "invalid_state",
      "message": "The current state of the resource does not allow the operation"
    }
  ]
}

{
  "type": "https://docs.filmo.io/errors/rate_limited",
  "title": "Rate limit exceeded",
  "status": 429,
  "code": "rate_limited",
  "detail": "Rate limit exceeded: retry in 30 seconds",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c",
  "retryAfter": 30
}

{
  "type": "https://docs.filmo.io/errors/internal_error",
  "title": "Internal error",
  "status": 500,
  "code": "internal_error",
  "detail": "Internal error",
  "requestId": "req_0b9f6c1d2e3a4f5a8b7c6d5e4f3a2b1c"
}

Generated from the schema

It NEVER writes anything: the engine runs without a single write tool loaded, and what it can read is bounded by the permission guardrail of the owner of the API key, table by table. It consumes AI credits of the account: without quota it responds 402 addon_required without ever asking the model. It can take tens of seconds on questions that chain several queries; if needsMoreContext comes true, the answer is empty and you should rephrase with more detail instead of retrying the same.

Authorizations

Bearer API key with the scope below. ai:ask

Body

application/json

Body schema: AiAskBody

questionstringRequired

Natural-language question about the data of your account. Required.

Limits: min length 1, max length 4000

webSearchbooleandefault:false

Also allows web search to answer. Defaults to false: only the data of the account is consulted.

modestringdefault:"instant"

Answer mode. Today only "instant" (a single pass, no conversation). Documented so that future modes are additive.

Available options: instant

Response

application/json

Successful response.

Response schema: AiAskDto

Envelope: AiAskResponse. meta.warnings is present only when the operation is deprecated.

Headers: X-Request-Id · RateLimit-Limit · RateLimit-Remaining · RateLimit-Reset · ETag

dataobject

The ai ask, as returned by the API.

Show child attributes

data.answerstring

Answer in markdown. Empty string when needsMoreContext is true.

data.needsMoreContextboolean

True when the AI finished without being able to answer and needs more context. In that case answer comes empty: rephrase the question with more detail instead of retrying as is.

data.webSearchSourcesobject[]

Cited web sources. Empty if web search was not requested or if none was used.

Show child attributes

data.webSearchSources.urlstring

URL of the consulted source.

data.webSearchSources.titlestring

Source title.

data.webSearchSources.faviconstring

URL of the site favicon, to render the source.

metaobject

Additional information about the response.

Show child attributes

meta.warningsobject[]

Lifecycle warnings; present only when the operation is deprecated.

Show child attributes

meta.warnings.codestring

Stable warning code.

Available options: deprecated

meta.warnings.messagestring

For people: what is deprecated, until when, and what to use.

meta.warnings.sunsetstring

Day (YYYY-MM-DD) the operation stops being served.

meta.warnings.replacementstring | null

operationId of the operation to use instead, or null if there is none.

meta.warnings.linkstring

Where the deprecation is documented (the changelog).

Errors

Status	Codes	Meaning
400	`validation_error`	Malformed query or body. `errors[]` lists every offending field with its stable code.
402	`addon_required`	The account plan does not include the add-on this operation needs; `requiredAddon` names it.
404	`not_found`	It does not exist or is outside the scope of the API key.
409	`conflict`	The current state of the resource prevents the operation, a request with that Idempotency-Key is already in progress, or another conditional write (`If-Match`) held the resource for more than five seconds. `errors[0].code` says which: `in_progress` and `lock_timeout` are solved by retrying; `invalid_state` is not, because the state of the resource forbids the operation.

401, 403, 429, 500 can be returned by any operation. Errors

Deprecation

This operation is not deprecated. Deprecations are announced with a Deprecation header and a sunset date. Versioning policy

Was this page helpful?

Request examples

Authorizations

Body

Response

Errors

Deprecation

Related