Skip to main content
POST
/
api
/
v1
/
agents
curl --request POST \
  --url https://api.staging.getmodus.com/api/v1/agents \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "Daily Sales Report",
  "type": "task"
}
'
{
  "id": 42,
  "slug": "customer-churn-agent-a3f",
  "name": "Customer Churn Analyzer",
  "status": "active",
  "type": "task",
  "orgUuid": "00000000-0000-0000-0000-000000000001",
  "hasUnpublishedChanges": false,
  "isEnabled": true,
  "accessConfig": {
    "visibility": "shared",
    "groupPermissions": {
      "group_eng_uuid": {
        "use": true,
        "manage": false
      }
    },
    "sharedWith": [],
    "ownerUserId": "user_2abc",
    "ownerEmail": "alice@example.com"
  },
  "createdAt": "2026-05-01T10:00:00.000Z",
  "updatedAt": "2026-05-11T10:00:00.000Z",
  "canManage": true,
  "canUse": true,
  "description": "Predicts churn risk for a customer given a 90-day usage window.",
  "activeVariationId": "00000000-0000-4000-a000-000000000100",
  "draftVariationId": "00000000-0000-4000-a000-000000000101",
  "pendingOwnershipTransfer": {
    "pendingOwnerUserId": "user_2abc123def456",
    "requestedByUserId": "user_2xyz789ghi012",
    "requestedAt": "2026-06-05T12:00:00.000Z",
    "pendingOwnerEmail": "newowner@example.com"
  },
  "variation": {
    "trigger": {},
    "workflowStructure": {},
    "agentSelection": {}
  },
  "deletedAt": null
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
name
string
required

Display name for the agent. Will be slugified into a URL-safe path.

Required string length: 1 - 200
Example:

"Daily Sales Report"

​
type
enum<string>
required

Agent type. task = single-step skill orchestration; workflow = multi-step graph.

Available options:
task,
workflow
Example:

"task"

​
description
string

Optional one-paragraph description shown in the builder and agent catalog.

Example:

"Generates a daily sales report from CRM data."

​
trigger
object

Trigger configuration (schedule / webhook / api / slack / manual). Schedule shape is fully validated; other trigger types are opaque.

​
agentSelection
object

Agent selection (for task automations): ordered skills plus per-skill instructions.

​
workflowStructure
object

Workflow graph (nodes + edges) for type=workflow agents. Free-form JSONB.

Example:
{ "nodes": [], "edges": [] }
​
accessConfig
object

Access configuration. Omit to use the default (full-org shared with use + manage).

Response

​
id
number
required

Numeric agent id (stable per-org; not reused after delete).

Example:

42

​
slug
string
required

URL-safe slug used in human-readable links. Unique per org.

Example:

"customer-churn-agent-a3f"

​
name
string
required

Display name of the agent. Shown in the builder and in run logs.

Example:

"Customer Churn Analyzer"

​
status
enum<string>
required

Lifecycle status. draft = never deployed. active = deployed. deleted = soft-deleted.

Available options:
draft,
active,
deleted
Example:

"active"

​
type
enum<string>
required

Type of automation. task = single-step skill orchestration; workflow = multi-step graph.

Available options:
task,
workflow
Example:

"task"

​
orgUuid
string
required

Org UUID this agent belongs to. Matches the caller’s principal.

Example:

"00000000-0000-0000-0000-000000000001"

​
hasUnpublishedChanges
boolean
required

True when the draft variation differs from the active variation (deploy would publish changes).

Example:

false

​
isEnabled
boolean
required

Whether the agent’s schedule is currently active. Toggle via POST /api/v1/agents/{id}/toggle.

Example:

true

​
accessConfig
object
required

Access configuration — who in the org can use / manage this agent.

​
createdAt
string
required

Creation timestamp.

Example:

"2026-05-01T10:00:00.000Z"

​
updatedAt
string
required

Most recent update timestamp.

Example:

"2026-05-11T10:00:00.000Z"

​
canManage
boolean
required

Whether the requesting principal can manage (edit/delete/deploy/toggle) this agent. Derived server-side from the principal + accessConfig. Always present on every Agent response.

Example:

true

​
canUse
boolean
required

Whether the requesting principal can use (run, view history of) this agent. Derived server-side from the principal + accessConfig. Always present on every Agent response.

Example:

true

​
description
string | null

Optional one-paragraph description of what this agent does.

Example:

"Predicts churn risk for a customer given a 90-day usage window."

​
activeVariationId
string | null

Active (deployed) variation id. Null until the agent is first deployed.

Example:

"00000000-0000-4000-a000-000000000100"

​
draftVariationId
string | null

Most recent draft variation id. Null when there is no draft pending.

Example:

"00000000-0000-4000-a000-000000000101"

​
pendingOwnershipTransfer
object

Pending ownership transfer awaiting recipient acceptance. Absent when no request is in flight.

​
variation
object

Variation-detail payload (trigger, workflowStructure, agentSelection) for the requested view. Populated by GET /api/v1/agents/:id; absent on list rows.

​
deletedAt
string | null

Soft-delete timestamp. Null for active agents.

Example:

null