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.

Prerequisites

Before you make your first API call, have the following ready:

• Kimara account with at least one published App.
• App ID — find this in the URL when you open an App in the gallery. For example, in https://kimara.ai/apps/abc123, the App ID is abc123.
• API key — generated from your account settings (see Authentication below).

Authentication

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

To create an API key:

1. Open Settings from the top navigation in Kimara.
2. Select the API Keys tab.
3. Click Generate New Key.
4. Copy the key immediately — it is shown only once. Store it somewhere secure such as an environment variable or a secrets manager.

Include the key in every request:

Authorization: Bearer <YOUR_API_KEY>

Never commit your API key to source control. Use environment variables (for example KIMARA_API_KEY) and reference them in your code.

Submitting a Run

Send a POST request to /runs with a JSON body that specifies the App ID and the inputs you want to pass.

curl -X POST https://api.kimara.ai/runs \
  -H "Authorization: Bearer <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "<APP_ID>",
    "inputs": {
      "prompt": "a beautiful landscape at sunset"
    }
  }'

The inputs object must match the input fields defined in the App. If an App exposes a prompt text field and an image upload field, both should be included (or rely on the defaults configured when the App was published).

A successful request returns a run object with a unique id:

{
  "id": "<RUN_ID>",
  "status": "queued"
}

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

Polling for Results

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

curl https://api.kimara.ai/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. Use output_url to retrieve the result.
• "failed" — the run encountered an error. Check the error field for details.

Example completed response:

{
  "id": "<RUN_ID>",
  "status": "completed",
  "output_url": "https://cdn.kimara.ai/outputs/..."
}

Poll at a reasonable interval — every 2–5 seconds is sufficient for most generation jobs. Polling more frequently than once per second is not recommended and may result in rate limiting.

Once status is "completed", download the result from output_url. The URL is time-limited, so retrieve the file 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.