Base URL: https://m8tes.ai/api/v2
All requests require an API key in the Authorization header:
Authorization: Bearer m8_your_key_here
Teammates
Teammates are reusable agent personas with instructions and tools.
Create Teammate
POST /teammates
| Field | Type | Required | Description |
|---|
| name | string | yes | Name |
| instructions | string | no | Instructions |
| tools | string[] | no | Tool names, e.g. ['gmail', 'slack'] |
| role | string | no | Agent persona role, e.g. 'Customer support specialist'. |
| goals | string | no | Agent goals. Injected into system prompt. |
| user_id | string | no | Your end-user ID for data isolation |
| metadata | object | no | Arbitrary key-value data |
| allowed_senders | string[] | no | Email addresses or @domain patterns allowed to email this teammate. Overrides default. |
Response 201 Created
List Teammates
GET /teammates
| Parameter | Type | Description |
|---|
| user_id | string | Filter by end-user ID |
| limit | int | Max results (1-100, default 20) |
| starting_after | int | Cursor: last item ID |
All list endpoints return a paginated envelope:
Use starting_after with the last item's ID to fetch the next page.
Get Teammate
GET /teammates/{teammate_id}
Response 200 OK
Update Teammate
PATCH /teammates/{teammate_id}
| Field | Type | Required | Description |
|---|
| name | string | no | Name |
| instructions | string | no | Instructions |
| tools | string[] | no | Tools |
| role | string | no | Role |
| goals | string | no | Goals |
| metadata | object | no | Metadata |
| allowed_senders | string[] | no | Allowed Senders |
Response 200 OK
Delete Teammate
Soft-deletes (archives) the teammate. Returns 204 No Content.
DELETE /teammates/{teammate_id}
Enable Email Inbox
POST /teammates/{teammate_id}/email-inbox
Disable Email Inbox
DELETE /teammates/{teammate_id}/email-inbox
Runs
Runs are task executions. They stream Server-Sent Events by default.
Create Run
POST /runs
| Field | Type | Required | Description |
|---|
| permission_mode | string | no | autonomous=auto-approve all tools, approval=pause and ask before tool use, plan=require plan approval before execution |
| human_in_the_loop | bool | no | Enable human-in-the-loop features: clarifying questions, tool approval, and plan approval. Required for non-autonomous permission modes. |
| teammate_id | int | no | Teammate Id |
| message | string | yes | Message |
| tools | string[] | no | Tools |
| stream | bool | no | Stream |
| name | string | no | Teammate name (creates new if no teammate_id) |
| instructions | string | no | Teammate instructions |
| user_id | string | no | Your end-user ID for data isolation |
| metadata | object | no | Arbitrary key-value data |
| memory | bool | no | Include saved per-user memories in agent context |
| history | bool | no | Include previous run results in agent context |
Streaming response: Server-Sent Events
data: {"type": "text-delta", "delta": "Hello"}
data: {"type": "tool-call-start", "toolName": "gmail_send", "toolCallId": "tc_1"}
data: {"type": "tool-result-end", "toolCallId": "tc_1", "result": "..."}
data: {"type": "done", "stop_reason": "end_turn"}
Non-streaming response 200 OK:
Polling: Non-streaming runs return immediately with status: "running". Poll GET /runs/{id} every 2 seconds until status is completed, failed, or cancelled.
Validation: permission_mode values approval and plan require human_in_the_loop=true.
Quick start: omit teammate_id and provide name to auto-create a teammate:
List Runs
GET /runs
| Parameter | Type | Description |
|---|
| teammate_id | int | Filter by teammate |
| user_id | string | Filter by end-user ID |
| status | string | Filter by status (running, paused, awaiting_approval, completed, failed, cancelled, closed, archived) |
| limit | int | Max results (1-100, default 20) |
| starting_after | int | Cursor: last item ID |
Get Run
GET /runs/{run_id}
Response 200 OK
Answer Question
POST /runs/{run_id}/answer
| Field | Type | Required | Description |
|---|
| answers | object | yes | Map of question text to selected option label |
Use this for AskUserQuestion responses.
- If the run is
running, the answer is stored and picked up by the active run.
- If the run is
awaiting_approval, the answer resumes execution.
- If the run is terminal (
completed/failed/cancelled), the API returns 409.
Plan mode approvals use this endpoint with {"Plan Approval": "Approve"}.
Approve Permission
POST /runs/{run_id}/approve
| Field | Type | Required | Description |
|---|
| request_id | string | yes | Permission request ID |
| decision | string | yes | Decision |
| remember | bool | no | Remember this decision for subsequent matching tool requests during the current run. For cross-run policies, use /permissions. |
Response status: after approval this returns a resolved status (allowed or denied), not pending.
Remember behavior: remember=true applies to subsequent matching requests during the current run. For persistent cross-run allowlists, use POST /permissions.
Response 200 OK
Cancel Run
Cancel an active run. Returns 409 if the run is already completed, failed, or cancelled.
POST /runs/{run_id}/cancel
Response 200 OK
Reply To Run
Send a follow-up message on an existing run to continue the conversation.
Behavior note: runs.reply() always executes as non-interactive. It does not enable AskUserQuestion, approval, or plan mode.
POST /runs/{run_id}/reply
| Field | Type | Required | Description |
|---|
| message | string | yes | Message |
| stream | bool | no | Stream |
List Run Permissions
Returns pending and resolved tool permission requests for runs using approval or plan mode. This list can include tool_name="AskUserQuestion" entries.
GET /runs/{run_id}/permissions
Update Permission Mode
PATCH /runs/{run_id}/permission-mode
| Field | Type | Required | Description |
|---|
| permission_mode | string | yes | Permission Mode |
Tasks
Tasks are reusable job definitions. Create a task, then attach triggers via tasks.triggers.create().
Create Task
POST /tasks
| Field | Type | Required | Description |
|---|
| teammate_id | int | yes | Teammate Id |
| name | string | no | Name |
| instructions | string | yes | Instructions |
| tools | string[] | no | Tools |
| expected_output | string | no | Description of expected output format. |
| goals | string | no | Task-specific goals. |
| user_id | string | no | Your end-user ID for data isolation |
Response 201 Created
List Tasks
GET /tasks
| Parameter | Type | Description |
|---|
| teammate_id | int | Filter by teammate |
| user_id | string | Filter by end-user ID |
| limit | int | Max results (1-100, default 20) |
| starting_after | int | Cursor: last item ID |
Get Task
GET /tasks/{task_id}
Response 200 OK
Update Task
PATCH /tasks/{task_id}
| Field | Type | Required | Description |
|---|
| name | string | no | Name |
| instructions | string | no | Instructions |
| tools | string[] | no | Tools |
| expected_output | string | no | Expected Output |
| goals | string | no | Goals |
Response 200 OK
Delete Task
DELETE /tasks/{task_id}
Run Task
POST /tasks/{task_id}/runs
| Field | Type | Required | Description |
|---|
| permission_mode | string | no | autonomous=auto-approve all tools, approval=pause and ask before tool use, plan=require plan approval before execution |
| human_in_the_loop | bool | no | Enable human-in-the-loop features: clarifying questions, tool approval, and plan approval. Required for non-autonomous permission modes. |
| stream | bool | no | Stream |
| user_id | string | no | Your end-user ID for data isolation |
| metadata | object | no | Arbitrary key-value data |
| memory | bool | no | Include saved per-user memories in agent context |
| history | bool | no | Include previous run results in agent context |
Validation: permission_mode values approval and plan require human_in_the_loop=true.
Create Trigger
POST /tasks/{task_id}/triggers
| Field | Type | Required | Description |
|---|
| type | string | yes | Type |
| cron | string | no | Cron |
| interval_seconds | int | no | Interval Seconds |
| timezone | string | no | Timezone |
Response 201 Created
List Triggers
GET /tasks/{task_id}/triggers
Delete Trigger
DELETE /tasks/{task_id}/triggers/{trigger_id}
Apps
List available tools, connect integrations via OAuth, and manage end-user connections.
List Apps
Pass user_id to check connection status for a specific end-user.
GET /apps
| Parameter | Type | Description |
|---|
| user_id | string | End-user ID to check connections for |
Connect App
POST /apps/{app_name}/connect
| Field | Type | Required | Description |
|---|
| redirect_uri | string | yes | URL to redirect after OAuth |
| user_id | string | no | End-user ID for multi-tenant connections |
Response 200 OK
Disconnect App
DELETE /apps/{app_name}/connections
| Parameter | Type | Description |
|---|
| user_id | string | End-user ID to disconnect |
Connect App Complete
After the user completes OAuth and is redirected back:
POST /apps/{app_name}/connect/complete
| Field | Type | Required | Description |
|---|
| connection_id | string | yes | Connection Id |
| user_id | string | no | End-user ID for multi-tenant connections |
Response 200 OK
Memories
Pre-populate or manage end-user memories. Memories are injected into the agent's context during execution to personalize responses.
Create Memory
POST /memories
| Field | Type | Required | Description |
|---|
| user_id | string | yes | End-user ID this memory belongs to |
| content | string | yes | Content |
Response 201 Created
List Memories
The user_id query parameter is required.
GET /memories
| Parameter | Type | Description |
|---|
| user_id | string | End-user ID to list memories for |
| limit | int | Max results (1-100, default 20) |
| starting_after | int | Cursor: last item ID |
Delete Memory
The user_id query parameter is required to prevent accidental deletion of account-level memories.
DELETE /memories/{memory_id}
| Parameter | Type | Description |
|---|
| user_id | string | End-user ID (prevents accidental deletion of account-level memories) |
Permissions
Pre-configure tool allow-lists for your end-users. Tools added here are auto-approved when runs use approval mode.
Create Permission
Idempotent: re-creating the same permission returns the existing record.
POST /permissions
| Field | Type | Required | Description |
|---|
| user_id | string | yes | End-user ID |
| tool | string | yes | Tool name to allow, e.g. 'gmail' |
Response 201 Created
List Permissions
GET /permissions
| Parameter | Type | Description |
|---|
| user_id | string | End-user ID to list permissions for |
| limit | int | Max results (1-100, default 20) |
| starting_after | int | Cursor: last item ID |
Delete Permission
DELETE /permissions/{permission_id}
| Parameter | Type | Description |
|---|
| user_id | string | End-user ID (prevents accidental cross-user deletion) |
Users
Manage end-user profiles. Profiles are auto-created when user_id is passed to any endpoint, or created explicitly with profile data.
Create End User
POST /users
| Field | Type | Required | Description |
|---|
| user_id | string | yes | Your end-user identifier |
| name | string | no | Name |
| email | string | no | Email |
| company | string | no | Company |
| metadata | object | no | Arbitrary key-value data |
Response 201 Created
List End Users
GET /users
| Parameter | Type | Description |
|---|
| limit | int | Max results (1-100, default 20) |
| starting_after | int | Cursor: last item ID |
Get End User
GET /users/{user_id}
Response 200 OK
Update End User
PATCH /users/{user_id}
| Field | Type | Required | Description |
|---|
| name | string | no | Name |
| email | string | no | Email |
| company | string | no | Company |
| metadata | object | no | Arbitrary key-value data |
Response 200 OK
Delete End User
DELETE /users/{user_id}
Settings
Account-level configuration. Control features like automatic company research.
Get Settings
GET /settings
Response 200 OK
Update Settings
PATCH /settings
| Field | Type | Required | Description |
|---|
| company_research | bool | no | Enable/disable automatic company research (default: enabled) |
Response 200 OK
Webhooks
Register URLs to receive signed event notifications when runs change status.
Create Webhook
POST /webhooks
| Field | Type | Required | Description |
|---|
| url | string | yes | HTTPS URL to receive events |
| events | string[] | no | Events: run.started, run.completed, run.failed, run.awaiting_input |
Note: The secret is only returned on creation. Store it securely.
Response 201 Created
List Webhooks
Secrets are masked in list responses.
GET /webhooks
| Parameter | Type | Description |
|---|
| limit | int | Max results (1-100, default 20) |
| starting_after | int | Cursor: last item ID |
Get Webhook
GET /webhooks/{webhook_id}
Response 200 OK
Update Webhook
PATCH /webhooks/{webhook_id}
| Field | Type | Required | Description |
|---|
| url | string | no | Url |
| events | string[] | no | Events |
| active | bool | no | Active |
| rotate_secret | bool | no | Generate a new signing secret |
Response 200 OK
Delete Webhook
DELETE /webhooks/{webhook_id}
List Deliveries
View delivery attempts for a webhook endpoint.
GET /webhooks/{webhook_id}/deliveries
| Parameter | Type | Description |
|---|
| limit | int | Max results (1-100, default 20) |
| starting_after | int | Cursor: last delivery ID |
Errors
All errors follow a standard format:
| Status | Type | SDK Exception | Description |
|---|
| 400 | invalid_request_error | APIError | Invalid request |
| 401 | authentication_error | AuthenticationError | Invalid or missing API key |
| 404 | not_found | NotFoundError | Resource not found |
| 409 | conflict_error | APIError | Resource conflict (duplicate, not active) |
| 422 | validation_error | ValidationError | Invalid request parameters |
| 429 | rate_limit_error | RateLimitError | Too many requests (auto-retried by SDK) |
| 500+ | api_error | APIError | Server error (auto-retried by SDK) |
