Apps Endpoint

The Apps API lets you execute reusable workflow apps built in Armox Canvas.

Base paths:

GET https://armox.ai/api/v1/apps
POST https://armox.ai/api/v1/apps/run

GET `/api/v1/apps`

Lists active template apps and private apps your user can access.

Request

curl -X GET "https://armox.ai/api/v1/apps" \
  -H "Authorization: Bearer sk_live_your_key_here"

Response (Important)

The inputs array is the contract for POST /api/v1/apps/run:

inputs[].id is the key you must send in inputs object
inputs[].required means the value must be present
inputs[].allowMultiple: true means send an array (for example, image URL list)
inputs[].targetHandle tells which model setting/input this maps to

Prompt Template

{
  "object": "list",
  "data": [
    {
      "id": "cb2bbd2d-b538-4d34-a54e-a9158c2e0dbb",
      "name": "Sketch to Render",
      "description": "Convert sketches into photorealistic renders",
      "icon": null,
      "thumbnail_url": "https://...",
      "is_template": true,
      "brain_id": "f53d5c9f-b91d-469c-9390-dd1552878255",
      "tags": ["Photorealistic Render"],
      "inputs": [
        {
          "id": "93197f6b-0180-4da1-ad4a-87890d2c7d4a",
          "type": "image",
          "label": "Input Images",
          "required": true,
          "targetHandle": "image_input",
          "allowMultiple": true
        },
        {
          "id": "ced4aa7b-a2a8-4b53-b9ea-1b3e7d9194b5",
          "type": "text",
          "label": "Aspect Ratio",
          "required": true,
          "targetHandle": "aspect_ratio"
        }
      ]
    }
  ]
}

POST `/api/v1/apps/run`

Executes one app workflow and returns an async job.

Request Body

Prompt Template

{
  "app_id": "cb2bbd2d-b538-4d34-a54e-a9158c2e0dbb",
  "inputs": {
    "93197f6b-0180-4da1-ad4a-87890d2c7d4a": [
      "https://example.com/reference-image.jpg"
    ],
    "ced4aa7b-a2a8-4b53-b9ea-1b3e7d9194b5": "auto"
  },
  "webhook_url": "https://your-app.com/webhooks/armox"
}

Fields:

app_id (required): app identifier from GET /api/v1/apps
inputs (object): key-value map where each key must be an inputs[].id returned by GET /api/v1/apps
webhook_url (optional): callback URL

Validation Rules

app must exist and be active
user must have access to non-template app resources
all required app inputs must be provided
input value type must match the app input contract (string vs array, etc.)

If required inputs are missing, response is 400 with:

{ "error": "Missing required inputs: Prompt" }

Response (`202`)

POST /api/v1/apps/run is asynchronous.

{
  "id": "0fefb57b-a89a-46f3-b7f6-da24841722f4",
  "object": "job",
  "status": "processing",
  "run_type": "app",
  "app_id": "cb2bbd2d-b538-4d34-a54e-a9158c2e0dbb",
  "app_name": "Sketch to Render",
  "credits_charged": 200,
  "created_at": "2026-04-06T11:15:14.964978+00:00"
}

End-to-End Example (Real Flow)

List apps with GET /api/v1/apps
Find your app and map inputs[].id -> values
Run it using POST /api/v1/apps/run
Poll GET /api/v1/jobs/:id until terminal state
Read outputs from output_data.node_outputs

cURL

Prompt Template

curl -X POST "https://armox.ai/api/v1/apps/run" \
  -H "Authorization: Bearer sk_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "cb2bbd2d-b538-4d34-a54e-a9158c2e0dbb",
    "inputs": {
      "93197f6b-0180-4da1-ad4a-87890d2c7d4a": [
        "https://example.com/reference-image.jpg"
      ],
      "ced4aa7b-a2a8-4b53-b9ea-1b3e7d9194b5": "auto"
    }
  }'

JavaScript

Prompt Template

const appId = "cb2bbd2d-b538-4d34-a54e-a9158c2e0dbb";

const runResponse = await fetch("https://armox.ai/api/v1/apps/run", {
  method: "POST",
  headers: {
    Authorization: "Bearer sk_live_your_key_here",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    app_id: appId,
    inputs: {
      "93197f6b-0180-4da1-ad4a-87890d2c7d4a": [
        "https://example.com/reference-image.jpg",
      ],
      "ced4aa7b-a2a8-4b53-b9ea-1b3e7d9194b5": "auto",
    },
  }),
});

const runJob = await runResponse.json();
console.log("Initial job:", runJob);

Typical Completed Job

Prompt Template

{
  "object": "job",
  "id": "0fefb57b-a89a-46f3-b7f6-da24841722f4",
  "run_type": "app",
  "model_id": null,
  "app_id": "cb2bbd2d-b538-4d34-a54e-a9158c2e0dbb",
  "status": "completed",
  "input_data": {
    "app_id": "cb2bbd2d-b538-4d34-a54e-a9158c2e0dbb",
    "inputs": {
      "93197f6b-0180-4da1-ad4a-87890d2c7d4a": [
        "https://example.com/reference-image.jpg"
      ],
      "ced4aa7b-a2a8-4b53-b9ea-1b3e7d9194b5": "auto"
    }
  },
  "output_data": {
    "app_id": "cb2bbd2d-b538-4d34-a54e-a9158c2e0dbb",
    "app_name": "Sketch to Render",
    "node_outputs": {
      "6fa95504-bf6c-44e6-bdda-c418903abc8c": {
        "outputImage": "https://armox-storage.s3.us-west-2.amazonaws.com/public/canvas-images/transform-this-architectural-h-2aebaf05-2c74-4b02-be78-979885f22aef.jpeg"
      }
    }
  },
  "error_message": null,
  "credits_charged": 200,
  "created_at": "2026-04-06T11:15:14.964978+00:00",
  "completed_at": "2026-04-06T11:17:14.985+00:00",
  "webhook_delivered": false
}

Reading `output_data.node_outputs`

node_outputs keys are internal node IDs (dynamic per app)
output payload varies by node/model (outputImage, outputVideo, outputAudio, etc.)
for app runs, model_id at job root is typically null

Polling Tip (Avoid 429)

Poll every 10-15 seconds instead of every 2-4 seconds
If you receive 429, read Retry-After, wait, then retry
Best practice: combine polling with webhook_url

Cost and Credits

Apps may run multiple nodes internally. Credits are deducted when the app run is accepted.

If the final job fails, credits are refunded according to job handling logic.

Apps Endpoint

GET /api/v1/apps

Request

Response (Important)

POST /api/v1/apps/run

Request Body

Validation Rules

Response (202)

End-to-End Example (Real Flow)

cURL

JavaScript

Typical Completed Job

Reading output_data.node_outputs

Polling Tip (Avoid 429)

Cost and Credits

Related Pages

准备好转变 您的创意工作流了吗？

GET `/api/v1/apps`

POST `/api/v1/apps/run`

Response (`202`)

Reading `output_data.node_outputs`

准备好转变您的创意工作流了吗？