Runs

A run executes an app: you supply the app's input fields, the API queues the work, and a worker fills in the response. Runs are asynchronous — creating one returns immediately with a new status, and you read the result back once it has finished. A run started through the API shows API as its origin in the workspace history.

Endpoints

<run_id> is a run identifier, prefixed runi_.

Note — The path segment is run but the scope is reasoning:read and reasoning:write, and the object is a reasoning. A key scoped run:* cannot call these endpoints. Use reasoning:*, or *.

The reasoning object

The model object carries the resolved build:

Statuses

Poll GET /v1/run/detail/<run_id> until the status is finished or failed. Both are final; every other status will change on its own.

Launch a run

POST /v1/run/create names an app and supplies its inputs.

curl -X POST https://api.thinkhx.com/v1/run/create \
  -H "Authorization: Bearer sk-project-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "mapp_0ceacb46e5b3a99e91b6",
    "data": { "message": "The checkout page has been down since this morning." }
  }'

{
  "code": 200,
  "title": "OK",
  "response": {
    "id": "runi_1b7f4e0c96a2d8531fca",
    "object": "reasoning",
    "data": { "message": "The checkout page has been down since this morning." },
    "instruction": { "1": "Classify the message as low, normal or urgent." },
    "status": "new",
    "created_at": 1754209200
  }
}

Keep the returned id and poll it. The creation response deliberately carries no response field: nothing has run yet.

Sending a document or an image

A field whose type is document or image (see Apps) does not take text: it takes a file your project has already uploaded to its own library. Send the file's identifier, prefixed file_, or its delivery URL — both are accepted and both are stored as the URL:

curl -X POST https://api.thinkhx.com/v1/run/create \
  -H "Authorization: Bearer sk-project-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "mapp_0ceacb46e5b3a99e91b6",
    "data": { "invoice": "file_9c1d4a70e58b23f6ad02" }
  }'

The engine reads the file before the model runs: a document becomes the text it contains, an image is handed to the model as a picture. Accepted document formats are PDF, DOCX, XLSX, CSV and TXT; images are PNG, JPG and WebP.

You can run your own apps and any published app of any project. An app that is not activated, or has no usable model, is refused with 422 and the general message.

The quota is checked before anything else, so an exhausted project cannot queue work. Read the remaining allowance from Quota and token usage.

Tip — A field can also be keyed by its madi_ identifier or by its position, counting from 1. Keying by name is the clearest and is what the app's schema gives you.

Read one run

GET /v1/run/detail/<run_id> returns the whole run, including the response once it exists.

curl https://api.thinkhx.com/v1/run/detail/runi_1b7f4e0c96a2d8531fca \
  -H "Authorization: Bearer sk-project-YOUR_KEY"

{
  "code": 200,
  "title": "OK",
  "response": {
    "id": "runi_1b7f4e0c96a2d8531fca",
    "object": "reasoning",
    "app_id": "mapp_0ceacb46e5b3a99e91b6",
    "model": {
      "id": "modi_7b1e4c2a9d05f3618ea4",
      "model_library": "mlyi_2c9a7f45b8e1d06a3427",
      "name": "thinkhx-reason",
      "parameter": "8B"
    },
    "data": { "message": "The checkout page has been down since this morning." },
    "instruction": {
      "miid_9a4c07e5b312df8641ca": "Classify the message as low, normal or urgent."
    },
    "response": {
      "miid_9a4c07e5b312df8641ca": "urgent"
    },
    "tokens": { "input": 412, "output": 3, "total": 415 },
    "status": "finished",
    "duration": 1.84,
    "started_at": 1754209202,
    "finished_at": 1754209204,
    "created_at": 1754209200,
    "updated_at": 1754209204
  }
}

instruction and response share their keys, so you can pair each answer with the instruction that produced it. A run of another project gives 404 and Reasoning not found.

List runs

GET /v1/run/list returns the project's runs, newest first.

curl "https://api.thinkhx.com/v1/run/list?app_id=mapp_0ceacb46e5b3a99e91b6&limit=2" \
  -H "Authorization: Bearer sk-project-YOUR_KEY"

{
  "code": 200,
  "title": "OK",
  "response": {
    "object": "list",
    "data": [
      {
        "id": "runi_1b7f4e0c96a2d8531fca",
        "object": "reasoning",
        "app_id": "mapp_0ceacb46e5b3a99e91b6",
        "status": "finished",
        "duration": 1.84,
        "started_at": 1754209202,
        "finished_at": 1754209204,
        "created_at": 1754209200,
        "updated_at": 1754209204,
        "tokens": { "input": 412, "output": 3, "total": 415 }
      }
    ],
    "total": 1
  }
}

The list omits data, instruction, response and model. Read a run to get them. Listing never touches the quota, so you can poll a history freely.