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

Prompt Template

{
  "object": "list",
  "data": [
    {
      "id": "app_123",
      "name": "Product Hero Creator",
      "description": "Generate hero product images from a short brief",
      "icon": "sparkles",
      "thumbnail_url": "https://...",
      "is_template": true,
      "brain_id": "brain_abc",
      "tags": ["marketing", "image"],
      "inputs": [
        {
          "id": "input_prompt",
          "label": "Prompt",
          "required": true
        }
      ]
    }
  ]
}

POST `/api/v1/apps/run`

Executes one app workflow and returns an async job.

Request Body

{
  "app_id": "app_123",
  "inputs": {
    "input_prompt": "Luxury perfume bottle, dramatic studio lighting, black background"
  },
  "webhook_url": "https://your-app.com/webhooks/armox"
}

Fields:

app_id (required): app identifier from GET /api/v1/apps
inputs (optional object): key-value input map by input id
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

If required inputs are missing, response is 400 with:

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

Response (`202`)

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

{
  "id": "job_456",
  "object": "job",
  "status": "processing",
  "run_type": "app",
  "app_id": "app_123",
  "app_name": "Product Hero Creator",
  "credits_charged": 340,
  "created_at": "2026-03-26T12:20:00.000Z"
}

End-to-End Example

List apps with GET /api/v1/apps
Pick one app and inspect its inputs
Run it using POST /api/v1/apps/run
Poll GET /api/v1/jobs/:id until completion
Read outputs from output_data.node_outputs

cURL

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": "app_123",
    "inputs": {
      "input_prompt": "Luxury perfume bottle, dramatic studio lighting, black background"
    }
  }'

JavaScript

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: "app_123",
    inputs: { input_prompt: "Luxury perfume bottle, dramatic studio lighting, black background" },
  }),
});

const job = await runResponse.json();
console.log(job);

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.