Start a mission
from your own code.

With one API key a program can start a mission, read what each agent produced and download the files. A mission started this way is planned, run and reviewed exactly like one you start in the app.

Get a key

A key belongs to you and to one workspace.

Open Settings in the workspace you want to use and create a key under API keys. It starts with xvk_ and is shown once — copy it then. You can keep up to ten keys per workspace and revoke any of them at any time.

Send the key in the Authorizationheader of every request. Missions started with it use your usage and count against your plan's limits. All addresses below start with https://api.xorviex.ai.

Start a mission

One request. The answer comes back at once; the work takes minutes.

POST /api/v1/public/missions

curl -X POST https://api.xorviex.ai/api/v1/public/missions \
  -H "Authorization: Bearer xvk_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Competitor pricing",
    "goal": "Find the current prices of our three main competitors and summarise them in a table.",
    "scope_level": 2,
    "callback_url": "https://example.com/hooks/xorviex"
  }'

title: Required. A short name, up to 500 characters.
goal: Required. What you want done, in plain language, up to 20,000 characters. Say where the result should go and in what form.
scope_level: Required. 1 (quick) to 5 (maximum). It limits how many agents are planned and how long each works, so it sets how much usage the mission can spend.
category: Optional. Any label, to group missions in the app.
callback_url: Optional. An https address we call once when the mission is resolved.

201 Created

{
  "id": "2f0c6c1e-…",
  "title": "Competitor pricing",
  "status": "spawning",
  "scope_level": 2,
  "ou_consumed": 0,
  "finished": false,
  "created_at": "2026-10-12T09:00:00Z"
}

Read the result

Ask until “finished” is true.

GET /api/v1/public/missions/{id}

curl https://api.xorviex.ai/api/v1/public/missions/2f0c6c1e-… \
  -H "Authorization: Bearer xvk_your_key"

200 OK

{
  "id": "2f0c6c1e-…",
  "status": "resolved",
  "finished": true,
  "ou_consumed": 412000,
  "agents": [
    {
      "name": "Pricing Researcher",
      "role": "intelligence",
      "status": "completed",
      "output": "…the agent's final answer…",
      "output_truncated": false
    }
  ],
  "files": [
    {
      "id": "9b1d…",
      "filename": "competitor-pricing.pdf",
      "mime_type": "application/pdf",
      "size_bytes": 48211,
      "download_path": "/api/v1/public/files/9b1d…"
    }
  ]
}

status is one of spawning, running, paused, resolved or failed; finished is true for the last two. An agent's output appears when that agent ends, and is cut at 20,000 characters with output_truncated set. GET /api/v1/public/missionslists your workspace's newest missions (20 by default, 50 at most with ?limit=).

A mission whose pause_reason is out_of_ou ran out of usage. It continues by itself once you add a plan or credit.

Download a file

Reports, sheets, charts — whatever the mission made.

GET /api/v1/public/files/{id}

curl -L https://api.xorviex.ai/api/v1/public/files/9b1d… \
  -H "Authorization: Bearer xvk_your_key" \
  -o competitor-pricing.pdf

The answer is the file itself. Only files of the key's own workspace can be fetched.

Be told when it is done

Instead of asking again and again.

Give a callback_url when you start the mission and we send one request to it when the mission is resolved:

What your address receives

POST https://example.com/hooks/xorviex
Content-Type: application/json

{
  "event": "mission.resolved",
  "mission_id": "2f0c6c1e-…",
  "status": "resolved",
  "result_path": "/api/v1/public/missions/2f0c6c1e-…"
}

It is sent once, with a ten-second wait and no second try, and it is not signed: treat it as a hint and read the result with your key before acting on it. Nothing is sent for a mission that fails or is paused, so keep a timeout of your own.

Start a mission from an event

No key: the address itself is the secret.

An event trigger is a mission that starts whenever another system calls its address. Create one under Recurring → Event triggers; its address is shown once. Whatever you post becomes the material the mission works on.

POST /api/triggers/{token}

curl -X POST https://api.xorviex.ai/api/triggers/xvt_your_trigger_token \
  -H "Content-Type: application/json" \
  -d '{"customer": "Acme", "message": "Demo request from the website"}'

The answer is 202 with a mission_id when a mission was started, 200 when the event was ignored (the trigger is paused, or it is not an event it listens for), and 429when the trigger's daily or per-minute limit, your plan or your usage refused it. A refused event is dropped, not kept for later. The body may be up to 256 KB.

Errors and limits

Every error answer is JSON with a “detail” that says what was wrong.

401: The key is missing, unknown or revoked, or its owner no longer has access to the workspace.
403: Your plan has no free mission slot right now, or there is no usage left.
404: No such mission or file in this key's workspace.
422: A field is missing or not valid; the answer says which.
429: Too many requests. Wait for the number of seconds in the Retry-After header.

The API can start and read missions. Editing memory, connecting apps and approving actions are done in the app. Questions: sales@xorviex.ai.

Start a missionfrom your own code.