How to Run Apps via API

The Kimara REST API lets you submit App runs and retrieve results from any environment that can make HTTP requests. This is useful for automating batch generation, integrating Kimara into your own product, or triggering runs from a CI pipeline or script.

Authentication

All API requests must include an Authorization header with a Bearer token.

To create an API key:

Include the key in every request:

Authorization: Bearer <YOUR_API_KEY>

Finding an App and Its Input Schema

Before submitting a run you need the App Version ID and the input keys it accepts. There are three ways to get them:

1. From the App page

Open any App in the Kimara gallery and copy the snippet from the API Snippet section. It contains the correct App Version ID and all input keys pre-filled with example values.

2. List available apps

GET /api/v1/apps returns the latest version of every App you can access, with its input schema included.

# All public apps + your own
curl 'https://kimara.ai/api/v1/apps' \
  -H 'Authorization: Bearer YOUR_API_KEY'

# Only apps you created, including unlisted and private ones
curl 'https://kimara.ai/api/v1/apps?owner=me' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response:

{
  "apps": [
    {
      "id": "<APP_VERSION_ID>",
      "public_name": "Landscape Generator",
      "description": "Generates landscape images from a text prompt.",
      "version": 1,
      "is_public": true,
      "is_restricted": false,
      "created_at": "2024-01-01T00:00:00.000Z",
      "updated_at": "2024-01-01T00:00:00.000Z",
      "inputs": [
        {
          "key": "6:text",
          "type": "STRING",
          "title": "Prompt",
          "placeholder": "a beautiful landscape at sunset"
        },
        {
          "key": "3:steps",
          "type": "INT",
          "title": "Steps",
          "placeholder": "20",
          "min": 1,
          "max": 50
        }
      ]
    }
  ],
  "has_more": false,
  "next_cursor": null
}

Use ?limit=N (1-100, default 20) and ?cursor=<id> to paginate through results.

3. Inspect a single app

GET /api/v1/apps/{appVersionId} returns the input schema and a ready-to-use api_snippet for a specific App Version.

curl 'https://kimara.ai/api/v1/apps/<APP_VERSION_ID>' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Response:

{
  "publicName": "Landscape Generator",
  "version": 1,
  "description": "Generates landscape images from a text prompt.",
  "inputs": [
    {
      "key": "6:text",
      "type": "STRING",
      "title": "Prompt",
      "placeholder": "a beautiful landscape at sunset"
    }
  ],
  "api_snippet": {
    "method": "POST",
    "url": "https://kimara.ai/api/v1/apps/<APP_VERSION_ID>",
    "headers": {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    "body": {
      "inputs": {
        "6:text": "a beautiful landscape at sunset"
      }
    }
  }
}

Uploading Input Assets

Some Apps accept image, video, or audio inputs. These are passed as an asset_id — upload the file first, then reference the returned ID in your run request.

Upload a file

POST /api/v1/assets accepts a multipart/form-data body with a file field.

curl -X POST 'https://kimara.ai/api/v1/assets' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'file=@/path/to/image.png'

A successful upload returns:

{
  "success": true,
  "data": {
    "asset_id": "<ASSET_ID>",
    "filename": "image.png",
    "content_type": "image/png"
  }
}

Use the asset in the request

Pass the asset_id as the value for any IMAGE, VIDEO, or AUDIO input in your run request:

{
  "inputs": {
    "3:cfg": 4,
    "6:text": "cat sits and tilts its head and starts to laugh",
    "60:image": "<ASSET_ID>"
  }
}

Submitting a Run

Send a POST request to /api/v1/apps/{appVersionId} with a JSON body containing the inputs for that App. Omitted inputs fall back to the placeholder values configured at app creation time.

curl -X POST 'https://kimara.ai/api/v1/apps/<APP_VERSION_ID>' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "inputs": {
    "6:text": "a beautiful landscape at sunset"
  }
}'

A successful request returns HTTP 202 with a run object:

{
  "run_id": "<RUN_ID>",
  "status": "queued",
  "created_at": "2024-01-01T00:00:00.000Z",
  "poll_url": "/api/v1/runs/<RUN_ID>"
}

Save the returned run_id — you will use it to poll for results.

Polling for Results

Generation takes time, so retrieve the result by polling GET /api/v1/runs/{run_id} until status changes to "completed".

curl 'https://kimara.ai/api/v1/runs/<RUN_ID>' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Check the status field in the response:

• "queued" — the run is waiting for a worker.
• "running" — generation is in progress.
• "completed" — the run finished successfully. Output files are in the outputs array.
• "failed" — the run encountered an error. Check the error_message field for details.

Example completed response:

{
  "run_id": "<RUN_ID>",
  "status": "completed",
  "created_at": "2024-01-01T00:00:00.000Z",
  "started_at": "2024-01-01T00:00:01.000Z",
  "completed_at": "2024-01-01T00:00:15.000Z",
  "outputs": [
    {
      "filename": "output.png",
      "url": "https://...",
      "content_type": "image/png",
      "size_bytes": 204800
    }
  ]
}

Once status is "completed", download files from the url fields in outputs. These URLs are time-limited, so retrieve files promptly after the run completes.

Next Steps

See the full API reference for complete endpoint documentation.

• How to Create and Publish an App — Build the App you want to run via the API.
• How to Use Studios — Understand how Apps relate to your Studio and manage team access.
• How to Open ComfyUI — Explore the underlying workflow editor that powers every App.