AI apps

An app is a reusable AI application: a model, a set of input fields your caller fills in, and the instructions sent to the model. You create apps through this resource, then run them through AI runs. An app is private to your project until you publish it.

Endpoints

<app_id> is an app identifier, prefixed mapp_. Editing acts on the detail path; there is no separate update path. The API does not delete apps.

The app object

Each entry of data describes one input field:

tokens covers the app's whole life, not the current billing cycle, and counts only your own project's runs of it. Runs that ended in an error are left out. See AI quota and token usage for the figures of the current cycle.

Create an app

POST /v1/ai/app/create needs a name, a description, at least one input field and at least one instruction.

Send category, model or model_library so the API can pick a model; model_library wins over model, which wins over category.

curl -X POST https://api.ultineo.com/v1/ai/app/create \
  -H "Authorization: Bearer sk-project-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Support triage",
    "description": "Sorts an inbound support message by urgency.",
    "category": "classify",
    "data": [
      { "type": "text area", "name": "message", "placeholder": "Paste the message", "required": true }
    ],
    "instruction": [
      { "type": "text", "instruction": "Classify the message as low, normal or urgent." }
    ]
  }'

{
  "code": 200,
  "title": "OK",
  "response": {
    "id": "mapp_0ceacb46e5b3a99e91b6",
    "object": "app",
    "name": "Support triage",
    "description": "Sorts an inbound support message by urgency.",
    "category": "classify",
    "catalog_category": "",
    "model": "modi_c2b7e9a1d3f0a8645c8e",
    "model_library": "mlyi_c2a1e7d9b4f30685c3a3",
    "data": {
      "madi_5d8b21c74e0af96b3d15": {
        "type": "text area",
        "value": "message",
        "placeholder": "Paste the message",
        "required": true
      }
    },
    "instruction": {
      "miid_9a4c07e5b312df8641ca": {
        "type": "text",
        "instruction": "Classify the message as low, normal or urgent."
      }
    },
    "status": "activated",
    "created_at": 1789206600
  }
}

Note — Creation answers 200, not 201, and its data and instruction are objects keyed by the new identifiers rather than the arrays the read endpoints return. Read the app back with GET /v1/ai/app/detail/<app_id> if you need the standard shape.

Field types

The type you send in data is one of the names below. Its identifier is also accepted, and it is the identifier the read endpoints return.

document and image fields do not take typed text: a run supplies a file already stored in your project's file library. See AI runs.

Instruction types

The type of each instruction says what kind of answer you expect:

Task categories

category takes one of these names (or its identifier): general, summarizing, writing, analyze, solving, decision, excracting, coding, translation, classify, chatting, scoring, embedding. Send the names exactly as written here.

List your apps

GET /v1/ai/app/list returns your project's own apps, newest first, excluding deleted ones. It accepts limit and offset.

curl "https://api.ultineo.com/v1/ai/app/list?limit=2" \
  -H "Authorization: Bearer sk-project-YOUR_KEY"

{
  "code": 200,
  "title": "OK",
  "response": {
    "object": "list",
    "data": [
      {
        "id": "mapp_0ceacb46e5b3a99e91b6",
        "object": "app",
        "name": "Support triage",
        "description": "Sorts an inbound support message by urgency.",
        "catalog_category": "",
        "type": "private",
        "status": "activated",
        "model": "modi_c2b7e9a1d3f0a8645c8e",
        "model_library": "mlyi_c2a1e7d9b4f30685c3a3",
        "runs": { "private": 12, "public": 0 },
        "tokens": { "input": 8420, "output": 3115, "total": 11535 },
        "created_at": 1789206600,
        "updated_at": 1789206600
      }
    ],
    "total": 1
  }
}

The list omits data, instruction and logo: read one app to get them.

Read one app

GET /v1/ai/app/detail/<app_id> returns the full object, including the input fields you need to launch a run.

curl https://api.ultineo.com/v1/ai/app/detail/mapp_0ceacb46e5b3a99e91b6 \
  -H "Authorization: Bearer sk-project-YOUR_KEY"

{
  "code": 200,
  "title": "OK",
  "response": {
    "id": "mapp_0ceacb46e5b3a99e91b6",
    "object": "app",
    "name": "Support triage",
    "description": "Sorts an inbound support message by urgency.",
    "catalog_category": "",
    "type": "private",
    "status": "activated",
    "logo": "",
    "model": "modi_c2b7e9a1d3f0a8645c8e",
    "model_library": "mlyi_c2a1e7d9b4f30685c3a3",
    "data": [
      {
        "id": "madi_5d8b21c74e0af96b3d15",
        "name": "message",
        "type": "mdti_fdd932b23e1fa82aa942",
        "placeholder": "Paste the message",
        "required": true
      }
    ],
    "instruction": [
      {
        "id": "miid_9a4c07e5b312df8641ca",
        "type": "aiti_d0c8a5e7b2f3a6c4e9d1",
        "instruction": "Classify the message as low, normal or urgent."
      }
    ],
    "runs": { "private": 12, "public": 0 },
    "tokens": { "input": 8420, "output": 3115, "total": 11535 },
    "created_at": 1789206600,
    "updated_at": 1789206600
  }
}

You can read your own apps in any status, and any activated public app of another project. Reading another project's public app hides what belongs to its owner: instruction comes back as null and runs.private as 0, and tokens reports what your own project spent on it. An app that does not exist or was deleted gives 404 and App not found.; another project's private app gives 422 and the general message.

Edit an app

PATCH /v1/ai/app/detail/<app_id> changes one or more of these fields of one of your own apps. Send at least one.

curl -X PATCH https://api.ultineo.com/v1/ai/app/detail/mapp_0ceacb46e5b3a99e91b6 \
  -H "Authorization: Bearer sk-project-YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Support triage (EN)" }'

{
  "code": 200,
  "title": "OK",
  "response": {
    "id": "mapp_0ceacb46e5b3a99e91b6",
    "object": "app",
    "name": "Support triage (EN)",
    "description": "Sorts an inbound support message by urgency.",
    "catalog_category": "",
    "type": "private",
    "status": "activated",
    "model": "modi_c2b7e9a1d3f0a8645c8e",
    "model_library": "mlyi_c2a1e7d9b4f30685c3a3",
    "created_at": 1789206600,
    "updated_at": 1789210200
  }
}

Publishing has two conditions: the app must already be activated, and it must carry a logo. Withdrawing an app always succeeds.