API

This section describes the runtime API: routes, request shapes, file handling, trigger webhooks, and error codes.

Base URL: https://app.monkedo.com

Every request requires a valid API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

A key can only access components you explicitly enabled when configuring the key. Requests for anything else are rejected.

The key's connection is applied automatically. Do not send _connection in inputs. Component schemas returned by the API omit that field.

Every request requires a valid API key in the Authorization header.

A key can only access components you explicitly enabled when configuring the key. Requests for anything else are rejected.

List Available Applications

GET /api/v1/components/apps

List apps this key can use.

Query Parameters

200: OK

[
  {
    "name": "Cubicl",
    "icon": "cubicl.png",
    "key": "cubicl"
  },
  {
    "name": "Email",
    "icon": "trigger/email.png",
    "key": "email"
  }
]

Get Component Definitions

GET /api/v1/components/list

Return definitions (inputs, outputs, descriptions) for all components this key may use.

Query Parameters

200: OK

[
  {
    "id": "action.cubicl.get-client",
    "name": "Get Client",
    "desc": "Gets client details. [See the docs here](https://docs.cubicl.io/api-integration/clients#get-client-by-id).",
    "appKey": "cubicl",
    "appName": "Cubicl",
    "icon": "cubicl.jpg",
    "isTrigger": false,
    "inputs": {
      "clientId": {
        "title": "clientId",
        "description": "The ID of the client to be retrieved.",
        "type": "string"
      }
    },
    "outputs": {
      "client": {
        "title": "client",
        "type": "object",
        "properties": {}
      }
    },
    "inputsWithQueryableOptions": [],
    "required": ["clientId"]
  }
]

inputs and outputs are JSON Schema. File fields use the shapes described in Files below.

inputsWithQueryableOptions lists input names whose option lists can be loaded through Get Dynamic Input Options. Only present when at least one input supports dynamic options.

Get Component Details

GET /api/v1/components/details/:componentKey

Return the full definition for one component, in the same JSON Schema format as the list endpoint.

Path Parameters

200: OK

// Same object shape as one item from GET /api/v1/components/list.

Get Dynamic Input Options

POST /api/api-keys/input-options

Load the option list for a component input whose choices depend on other inputs (for example, a project list that changes after you pick an account).

Use inputsWithQueryableOptions from the component definition to see which input names support this endpoint.

Body

200: OK

[
  { "value": "GROUP_ID_1", "label": "My Project 1", "desc": "GROUP_ID_1" },
  { "value": "GROUP_ID_2", "label": "My Project 2", "desc": "GROUP_ID_2" },
]

The API key's configured connection is used automatically when the component requires authentication.

Create File Upload Link

POST /api/v1/files/upload-link

Reserve a file and get a presigned upload URL. Use this for large files instead of sending base64 in Run Component.

Body

200: OK

{
  "fileId": "507f1f77bcf86cd799439011",
  "s3Name": "507f1f77bcf86cd799439011-report.pdf",
  "uploadUrl": "https://..."
}

1. POST this endpoint to get uploadUrl and fileId.

2. PUT the file bytes to uploadUrl.

3. Pass { "name": "report.pdf", "fileId": "507f1f77bcf86cd799439011" } as the file input when running a component.

Files uploaded this way are not subject to the 100 MB limit that applies to base64 and URL inputs.

The presigned URL expires after 15 minutes.

Run Component

POST /api/v1/components/:componentId/run

Execute an action.

Path Parameters

Body

200: OK

{
  "name": "Result name",
  "outputs": {
    "result": "VALUE"
  },
  "componentId": "action.misc.logger",
  "creditsUsed": 1
}

outputs contains raw values, File outputs are { name, size, url }. Paid components may consume credits from your team's balance.

List Registered Triggers

GET /api/v1/components/triggers

200: OK

[
  {
    "_id": "6a295afb530d2213967340c1",
    "componentId": "trigger.cubicl.task-archived",
    "inputs": {
      "group": "GROUP_ID"
    },
    "createdAt": "2026-06-10T12:39:23.183Z",
    "webhookUrl": "https://hooks.example.com/listen"
  }
]

Register Trigger

POST /api/v1/components/triggers

Register a trigger. When it fires, Monkedo POSTs JSON to webhookUrl:

{
  "triggerId": "6a296203f6dd56f7cd1d4313",
  "componentId": "trigger.cubicl.task-created",
  "success": true,
  "outputs": {
    "task": { }
  }
}

File values inside outputs use { name, size, url }, same as run results.

Body

200: OK

{
  "triggerId": "6a296203f6dd56f7cd1d4313"
}

webhookUrl must be reachable from the internet. For local development, use a tunnel such as NGROK.

Polling vs webhook triggers

Your webhookUrl is always how you receive events. The difference is how Monkedo learns that something happened in the app:

Unregister Trigger

DELETE /api/v1/components/triggers/:triggerId

Remove a trigger. Returns 404 if the trigger does not belong to this key.

Path Parameters

200: OK

// Empty

File inputs (including List<File>, such as Send Email attachments):

{
  "name": "note.txt",
  "base64": "SGVsbG8="
}

or a public download URL:

{
  "name": "note.txt",
  "url": "https://example.com/note.txt"
}

or a file reserved through Create File Upload Link:

{
  "name": "note.txt",
  "fileId": "507f1f77bcf86cd799439011"
}

Rules:

• name is required and must include the extension. It cannot contain /, \, or :.

• Provide base64, url, or fileId. If both base64 and url are set, base64 is used.

• Max size is 100 MB for base64 and url inputs. The fileId path has no 100 MB cap.

• url must be public HTTP(S). Localhost and private IPs are rejected.

File outputs (run results and trigger webhooks):

{
  "name": "report.pdf",
  "size": 2048,
  "url": "https://monkedo.s3.<region>.backblazeb2.com/<object>"
}

Errors are returned as JSON with an HTTP status code:

{
  "statusCode": 403,
  "message": "Invalid API key.",
  "error": "Forbidden"
}

Authentication (403 Forbidden)

Authorization (403 Forbidden)

Not found (404)

Validation (400 Bad Request)

Runtime failures

Replace YOUR_API_KEY with your secret.

# List apps enabled on this key
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://app.monkedo.com/api/v1/components/apps

# List Email components only
curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://app.monkedo.com/api/v1/components/list?appKey=email"

# Load dynamic options for an input
curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"componentId": "action.cubicl.get-tasks", "inputName": "group", "inputs": {}}' \
  https://app.monkedo.com/api/api-keys/input-options

# Reserve a large file upload
curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "large-video.mp4"}' \
  https://app.monkedo.com/api/v1/files/upload-link

# Run an action
curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"inputs": {"getOnlyNames": true, "limit": 50, "skip": 0}}' \
  https://app.monkedo.com/api/v1/components/action.cubicl.get-clients/run

# Send email with a file attachment
curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inputs": {
      "to": ["user@example.com"],
      "subject": "File Test",
      "body": "Hello",
      "saveToSent": false,
      "attachments": [{ "name": "note.txt", "base64": "SGVsbG8=" }]
    }
  }' \
  https://app.monkedo.com/api/v1/components/action.email.send-email/run

# Register a trigger (events are POSTed to webhookUrl)
curl -X POST \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "componentKey": "trigger.cubicl.task-created",
    "webhookUrl": "https://hooks.example.com/listen",
    "inputs": { "group": "GROUP_ID" }
  }' \
  https://app.monkedo.com/api/v1/components/triggers