API

This section provides a comprehensive overview of the routes, types, and error codes for the features in the system, ensuring developers understand how to interact with the API and handle potent.

Component definitions returned by list and details, and results returned by run, use Monkedo's Value type system. Each value is an object with two fields:

{
  "type": { "id": 2 },
  "data": "hello"
}

TypeId reference

Composite types in component definitions

When you call list or details, each input and output includes a type object. Common patterns:

If an entity schema is known, schema is an array of [fieldName, fieldType] pairs:

{
  "id": 9,
  "schema": [
    ["length", { "id": 3 }],
    ["unit", { "id": 2 }]
  ]
}

File values

When an input expects type File (id: 8), data must be a file reference:

{
  "type": { "id": 8 },
  "data": {
    "_id": "507f1f77bcf86cd799439011",
    "name": "report.pdf",
    "size": 102400,
    "s3Name": "uploads/abc123.pdf"
  }
}

!! File references are created through Monkedo's file upload flow; you typically obtain them from a prior action output rather than constructing them manually.

Sending inputs to run

POST /api/v1/components/:componentId/run expects each entry in inputs to be a Value object — not a raw string or number.

Use the component's inputs array from list or details to determine field names and types, then wrap each value accordingly.

Do not send _connection. Monkedo injects the connection configured on your API key automatically.

Example — action.cubicl.get-client

Component input clientId has type Text (id: 2):

{
  "inputs": {
    "clientId": {
      "type": { "id": 2 },
      "data": "507f1f77bcf86cd799439011"
    }
  }
}

Example — action.google-sheets.get-values

After reading the component definition, a typical request looks like:

{
  "inputs": {
    "sheetId": {
      "type": { "id": 2 },
      "data": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgvE2upms"
    },
    "sheetName": {
      "type": { "id": 2 },
      "data": "Sheet1"
    },
    "hasHeaderRow": {
      "type": { "id": 4 },
      "data": true
    }
  }
}

Optional inputs can be omitted unless the component requires them.

Run response outputs

Successful run responses include an outputs object. Each output is also a Value:

{
  "name": "Client (Acme Corp)",
  "outputs": {
    "client": {
      "type": { "id": 9, "schema": [], "generic": "?", "genericSchema": true },
      "data": {
        "name": "Acme Corp",
        "email": "contact@acme.com"
      }
    },
    "customFields": {
      "type": { "id": 10, "schema": { "id": 9, "schema": [], "generic": "?", "genericSchema": true } },
      "data": []
    }
  },
  "componentId": "action.cubicl.get-client"
}

Read output data from outputs.<outputName>.data.

Trigger registration inputs

POST /api/v1/components/triggers uses plain JSON for inputs, not Value objects. Pass settings directly as defined by the trigger component:

{
  "componentKey": "trigger.schedule",
  "inputs": {
    "type": "interval",
    "interval": { "length": 20, "unit": "minute" }
  }
}

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 available to this key.

200: OK

[
  {
    "name": "Cubicl",
    "icon": "cubicl.png",
    "key": "cubicl"
  }
]

Get Component Definitions

GET api/v1/components/list

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

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).',
    auth: 'apiKey',
    appKey: 'cubicl',
    appName: 'Cubicl',
    keywords: ['get customer', 'find client', 'fetch client'],
    inputs: [
      {
        name: 'clientId',
	type: TypeId.Text,
	desc: 'The ID of the client to be retrieved.',
      },
    ],
    outputs: [
      {
	name: 'client',
	type: TypeId.Entity<?>,
      },
      {
	name: 'customFields',
	type: TypeId.List<Entity<?>>,
	desc: 'Shows the names of the "id" values in the customFields field of the client. If not defined in the Cubicl, it comes empty.',
      },
      {
	name: 'notFound',
	type: TypeId.Empty,
	color: '#e9596e',
      },
    ],
  }
]

Get Component Details

GET api/v1/components/details/:componentKey

Return the full definition for one component.

Path Parameters

200: OK

// Component Details

Run Component

GET api/v1/components/:componentId/run

Execute an action.

Path Parameters

Body

200: OK

{
  "name": "Result name",
  "outputs": {
    "result": {
      "type": TypeId.Text,
      "data": "value"
    }
  },
  "componentId": "action.misc.logger",
  "creditsUsed": 1
}

Each entry in outputs is a typed value (type + data). Paid components may consume credits from your team's balance.

List Registered Triggers

List triggers registered with this key.

200: OK

[
  {
    "_id": "...",
    "componentId": "trigger.schedule",
    "inputs": {
      "type": "interval",
      "interval": { "length": 20, "unit": "minute" }
    },
    "createdAt": "..."
  }
]

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

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 and the base URL with your values.

# List allowed components
curl -H "Authorization: Bearer YOUR_API_KEY" \
  https://app.monkedo.com/api/v1/components/list

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