# Modus API ## Docs - [Chat with a published agent (buffered, continue thread)](https://docs.staging.getmodus.com/api-reference/agents-·-chat/chat-with-a-published-agent-buffered-continue-thread.md): Continues a task-agent conversation (`api-auto-{agentId}-…`). Workflow agents do not support multi-turn continuity; each call may run a new workflow execution. - [Chat with a published agent (buffered, new thread)](https://docs.staging.getmodus.com/api-reference/agents-·-chat/chat-with-a-published-agent-buffered-new-thread.md): Starts a new conversation with a published task or workflow agent. Task agents use agent-service; workflow agents run via Temporal. Returns `threadId` for task-agent follow-up via POST …/conversations/{threadId}/chat. Workflow threads are ephemeral. Requires `model`. - [Get a single run (live state or history)](https://docs.staging.getmodus.com/api-reference/agents-·-runs/get-a-single-run-live-state-or-history.md): Returns either the live Temporal workflow query (for running / awaiting_human runs) or the hydrated history payload. Requires `agents:invoke`. - [List recent runs for an agent](https://docs.staging.getmodus.com/api-reference/agents-·-runs/list-recent-runs-for-an-agent.md): Returns Temporal-indexed run history for the agent. Supports status / timeframe / search filters and AIP-158 page-token pagination via the underlying Temporal visibility API. Requires `agents:invoke`. - [Create a run and stream events via SSE](https://docs.staging.getmodus.com/api-reference/agents-·-streaming/create-a-run-and-stream-events-via-sse.md): Starts a new agent chat run (or resumes an existing one using the Idempotency-Key header) and streams run events back to the caller as Server-Sent Events. - [Execute a workflow action and stream events via SSE](https://docs.staging.getmodus.com/api-reference/agents-·-streaming/execute-a-workflow-action-and-stream-events-via-sse.md): Executes a single workflow action step (tool invocation with runtime context) and streams the result back as Server-Sent Events. Same idempotency and resume semantics as POST /agent/runs: a retry with the same Idempotency-Key + same body resumes the existing stream. - [Resume or watch an existing run's SSE event stream](https://docs.staging.getmodus.com/api-reference/agents-·-streaming/resume-or-watch-an-existing-runs-sse-event-stream.md): Opens an SSE connection to an already-started run. Replays events from the `Last-Event-ID` header (or from offset 0 if absent), then blocks for new events until the run reaches a terminal state (`done`/`error`/`cancelled`) or the client disconnects. - [Accept a pending agent ownership transfer](https://docs.staging.getmodus.com/api-reference/agents/accept-a-pending-agent-ownership-transfer.md): Accepts a pending ownership transfer. Only the pending recipient may invoke this action. - [Cancel or decline a pending agent ownership transfer](https://docs.staging.getmodus.com/api-reference/agents/cancel-or-decline-a-pending-agent-ownership-transfer.md): Cancels a pending ownership transfer. The current owner may cancel; the pending recipient may decline. - [Create a new agent](https://docs.staging.getmodus.com/api-reference/agents/create-a-new-agent.md): Creates a new agent in the caller’s organization. The owner is set from the principal; access config defaults to org-shared `use` + `manage` when not specified. Returns the newly-created agent in draft state — call POST /api/v1/agents/{id}/deploy to publish it. - [Deploy the current draft variation](https://docs.staging.getmodus.com/api-reference/agents/deploy-the-current-draft-variation.md): Promotes the latest draft variation to active. First deploy enables the agent schedule; subsequent deploys preserve `isEnabled`. The response contains the post-deploy agent and a server-side `deployedAt` timestamp. Downstream side effects (git push, Temporal schedule update, Slack notification) run… - [Fetch a single agent by id](https://docs.staging.getmodus.com/api-reference/agents/fetch-a-single-agent-by-id.md): Returns the requested agent. `?view=draft` (default) reads the latest builder snapshot; `?view=active` reads the deployed variation. When the caller cannot manage the agent, the response is 404 (existence is hidden — same status as a missing row). Use list to discover agents you can run. - [List agents in the caller’s organization](https://docs.staging.getmodus.com/api-reference/agents/list-agents-in-the-caller’s-organization.md): Returns a paginated page of agents the caller can at least `use`. Agents the caller cannot see are filtered out (existence is hidden — no 404 enumeration). Pagination uses an opaque token returned in `nextPageToken` (AIP-158). - [Request agent ownership transfer to another org member](https://docs.staging.getmodus.com/api-reference/agents/request-agent-ownership-transfer-to-another-org-member.md): Requests ownership transfer to another organization member. Only the current owner may invoke this action. The recipient must accept before ownership changes. - [Soft-delete an agent](https://docs.staging.getmodus.com/api-reference/agents/soft-delete-an-agent.md): Marks the agent as deleted. The row is retained (audit) but excluded from default reads. Idempotent — deleting an already-deleted agent is a 204 no-op. Requires manage permission on the agent. Cleanup of the Temporal schedule is best-effort. - [Undelete a soft-deleted agent](https://docs.staging.getmodus.com/api-reference/agents/undelete-a-soft-deleted-agent.md): AIP-164. Restores a soft-deleted agent by clearing its tombstone flag and returns the resulting draft snapshot. Idempotent — undeleting an already-active agent returns the agent unchanged. Requires manage permission on the underlying row; a missing or cross-org id surfaces as 404 (existence is hidde… - [Update an agent](https://docs.staging.getmodus.com/api-reference/agents/update-an-agent.md): Writes the supplied fields into the draft variation. Edits to `accessConfig` that would lock the caller out of `use` + `manage` are rejected (422). Returns the updated agent (draft view) — call POST /api/v1/agents/{id}/deploy to publish the changes. Pass `?updateMask=` (AIP-134) to restrict the… - [List integration connections in the caller’s organization](https://docs.staging.getmodus.com/api-reference/connections/list-integration-connections-in-the-caller’s-organization.md): Returns a paginated page of warehouse and SaaS integration connections the caller can `use`. Connections the caller cannot access are filtered out (existence is hidden — no 404 enumeration). Use the returned `id` when creating saved-query context items. Pagination uses an opaque token returned in `n… - [Create a dimension context item](https://docs.staging.getmodus.com/api-reference/context/create-a-dimension-context-item.md): Creates a semantic-layer dimension definition. NOTE: the underlying writer is not yet implemented (the legacy lambda throws here too) — the endpoint validates the input and returns 422 with a stable error message until the semantic-layer writer is wired. - [Create a fact context item](https://docs.staging.getmodus.com/api-reference/context/create-a-fact-context-item.md): Creates a semantic-layer fact definition. NOTE: the underlying writer is not yet implemented — the endpoint validates the input and returns 422 with a stable error message until the writer is wired. - [Create a filter context item](https://docs.staging.getmodus.com/api-reference/context/create-a-filter-context-item.md): Creates a semantic-layer filter definition. NOTE: the underlying writer is not yet implemented — the endpoint validates the input and returns 422 with a stable error message until the writer is wired. - [Create a link context item by extracting / crawling a URL](https://docs.staging.getmodus.com/api-reference/context/create-a-link-context-item-by-extracting-crawling-a-url.md): Invokes the Tavily access Lambda to extract content from the supplied URL (single-page) or crawl up to `pageLimit` pages when `isCrawl` is true. The extracted markdown is stored in tenant S3; only metadata is kept on the context_items row. - [Create a metric context item](https://docs.staging.getmodus.com/api-reference/context/create-a-metric-context-item.md): Creates a semantic-layer metric definition. NOTE: the underlying writer is not yet implemented — the endpoint validates the input and returns 422 with a stable error message until the writer is wired. - [Create a note context item](https://docs.staging.getmodus.com/api-reference/context/create-a-note-context-item.md): Stores a markdown-formatted note in the caller’s tenant S3 bucket and a row in `context_items` so the note participates in selection / search like any other context item. - [Create a saved-query context item](https://docs.staging.getmodus.com/api-reference/context/create-a-saved-query-context-item.md): Persists a SQL snippet plus its target connection. The SQL text is stored in tenant S3; the metadata (connection id, optional hierarchical path, optional description) lives on the context_items row so the snippet participates in selection / search. - [Delete a user-created context item](https://docs.staging.getmodus.com/api-reference/context/delete-a-user-created-context-item.md): Removes a context item created via the SPA / public API. Only items in the user-created allowlist (`note`, `link`, `saved_query`, `golden_query`, `file_upload`) can be deleted via this surface — integration-derived items are managed by their owning syncer and respond with 422. Returns 404 when the r… - [Exact single-item lookup by (contextType, dataPath)](https://docs.staging.getmodus.com/api-reference/context/exact-single-item-lookup-by-contexttype-datapath.md): Returns the matching row or `{item: null}` when no exact match exists. Full-equality match on `data_path`; partial / prefix matches are NOT supported here. The optional `contentProjection` shrinks the `content` payload at SQL time (top-level scalar fields plus per-element keys inside array-valued fi… - [Fetch a single context item by uid](https://docs.staging.getmodus.com/api-reference/context/fetch-a-single-context-item-by-uid.md): Returns one context item by its stable UUID. Returns 404 when the row is missing in the caller’s tenant schema (existence is hidden — same status as a missing row in another org). - [List context items in the caller’s organization](https://docs.staging.getmodus.com/api-reference/context/list-context-items-in-the-caller’s-organization.md): Returns a paginated page of context items, optionally filtered by context type, verification status, topic, or free-text search. Pagination uses an opaque token returned in `nextPageToken` — round-trip the string as `pageToken` on the next request (AIP-158). Tenant isolation is enforced by the org-s… - [List values extracted from a context item at the given JSON path](https://docs.staging.getmodus.com/api-reference/context/list-values-extracted-from-a-context-item-at-the-given-json-path.md): Reads a paginated slice of values from inside the item’s `content` JSON at the supplied `contentKeyPath`. Useful for paging through array-valued content fields (e.g. enumerated values, sample data) without round-tripping the whole item. Returns the strict AIP-132 / AIP-158 shape `{ values, nextPageT… - [Update a context item](https://docs.staging.getmodus.com/api-reference/context/update-a-context-item.md): Patches one or more of {`content` (+ required `contextType`), `description`, `userFeedback`, `topics`} on an existing context item. The audit metadata records the editing user’s id, name, and email. Returns the uid of the patched item. Pass `?updateMask=` (AIP-134) to restrict the write to spec… - [Chat with a published skill (buffered, continue thread)](https://docs.staging.getmodus.com/api-reference/skills-·-chat/chat-with-a-published-skill-buffered-continue-thread.md): Sends a message in an existing conversation. `threadId` is the path parameter (same id as GET …/conversations/{threadId}). Requires `model`. - [Chat with a published skill (buffered, new thread)](https://docs.staging.getmodus.com/api-reference/skills-·-chat/chat-with-a-published-skill-buffered-new-thread.md): Starts a new conversation with the published skill supervisor. Returns `threadId` for follow-up via POST …/conversations/{threadId}/chat. Requires `model` on every request. - [Compose published skill context](https://docs.staging.getmodus.com/api-reference/skills-·-context/compose-published-skill-context.md): Runs the published skill context composer (RAG / context-store) for the supplied user message without invoking the LLM. Returns composed context text for inspection or downstream use. Requires `skills:invoke` and `use` access on the skill. - [Fetch a single conversation by thread id](https://docs.staging.getmodus.com/api-reference/skills-·-conversations/fetch-a-single-conversation-by-thread-id.md): Returns the full conversation history (chronologically ordered messages) for a thread/checkpoint id. Conversations can span multiple agents, so the path id is a permission scope rather than conversation ownership. Use `id=0` for the SPA cross-skill scope. - [List conversations for a skill scope](https://docs.staging.getmodus.com/api-reference/skills-·-conversations/list-conversations-for-a-skill-scope.md): Returns a page of conversation summaries (newest-updated first) for the given skill scope. `id=0` lists cross-skill recent history for the caller. `userId`, `toolName`, and `timeframe` filters are optional. Pagination uses the AIP-158 `pageToken` / `pageSize` / `nextPageToken` contract; under the ho… - [Delete a memory](https://docs.staging.getmodus.com/api-reference/skills-·-memories/delete-a-memory.md): Removes one memory from mem0. Idempotent — deleting an already-deleted memory is a 204 no-op. Requires manage permission on the skill. - [List memories for a skill](https://docs.staging.getmodus.com/api-reference/skills-·-memories/list-memories-for-a-skill.md): Returns a page of memories stored against the skill in mem0. Caller must at least `use` the skill; otherwise a 404 is returned (existence is hidden). Pagination follows AIP-158 (`pageToken`, `pageSize`, `nextPageToken`). When no pagination query params are sent, the default page size is 100 (legacy… - [Semantic search over a skill's memories](https://docs.staging.getmodus.com/api-reference/skills-·-memories/semantic-search-over-a-skills-memories.md): Returns memories ranked by semantic similarity to the supplied `query`. Caller must at least `use` the skill. Optional `userId` and `limit` body fields narrow the result set (legacy parity with `search-memories`). - [Update a memory](https://docs.staging.getmodus.com/api-reference/skills-·-memories/update-a-memory.md): Patches one memory in mem0. At least one of `memory` / `metadata` must be supplied. Requires manage permission on the skill. Pass `?updateMask=` (AIP-134) to restrict the write to specific top-level fields; an absent mask preserves the legacy "write every body field" behaviour. - [Accept a pending skill ownership transfer](https://docs.staging.getmodus.com/api-reference/skills/accept-a-pending-skill-ownership-transfer.md): Accepts a pending ownership transfer. Only the pending recipient may invoke this action. - [Apply MCP interface config to the published skill](https://docs.staging.getmodus.com/api-reference/skills/apply-mcp-interface-config-to-the-published-skill.md): Writes coreTools, mcpToolExposure, and other MCP-tab fields to the active variation immediately so MCP clients see the change without a full skill deploy. Mirrors the same config onto a forked draft when present. Requires manage permission; unpublished skills return 404. - [Cancel or decline a pending skill ownership transfer](https://docs.staging.getmodus.com/api-reference/skills/cancel-or-decline-a-pending-skill-ownership-transfer.md): Cancels a pending ownership transfer. The current owner may cancel; the pending recipient may decline. - [Create a new skill](https://docs.staging.getmodus.com/api-reference/skills/create-a-new-skill.md): Creates a new skill in the caller’s organization. The owner is set from the principal; access config defaults to org-shared `use` + `manage` when not specified. Returns the newly-created skill in draft state — call POST /api/v1/skills/{id}/deploy to publish it. - [Deploy the current draft variation](https://docs.staging.getmodus.com/api-reference/skills/deploy-the-current-draft-variation.md): Promotes the latest draft variation to active. The response contains the post-deploy skill (with `hasUnpublishedChanges=false`) and a server-side `deployedAt` timestamp. The legacy git-push + change-detection side effects are deferred — the v1 only flips the active variation pointer. - [Fetch a historic variation of a skill](https://docs.staging.getmodus.com/api-reference/skills/fetch-a-historic-variation-of-a-skill.md): Returns the requested skill with the `variation` block populated from the specified historic variation (the `activeVariationId` on the response still reflects the live deployment). Same access-hiding 404 contract as GET /skills/:id — the caller must be able to at least `use` the skill, otherwise the… - [Fetch a single skill by id](https://docs.staging.getmodus.com/api-reference/skills/fetch-a-single-skill-by-id.md): Returns the requested skill. `?view=active` (default) reads the deployed variation; `?view=draft` reads the latest builder snapshot. When the caller cannot at least `use` the skill, the response is 404 (existence is hidden — same status as a missing row). - [List skills in the caller’s organization](https://docs.staging.getmodus.com/api-reference/skills/list-skills-in-the-caller’s-organization.md): Returns a paginated page of skills the caller can at least `use`. Skills the caller cannot see are filtered out (existence is hidden — no 404 enumeration). Pagination uses an opaque token returned in `nextPageToken` (AIP-158). - [Request skill ownership transfer to another org member](https://docs.staging.getmodus.com/api-reference/skills/request-skill-ownership-transfer-to-another-org-member.md): Requests ownership transfer to another organization member. Only the current owner may invoke this action. The recipient must accept before ownership changes. - [Soft-delete a skill](https://docs.staging.getmodus.com/api-reference/skills/soft-delete-a-skill.md): Marks the skill as deleted. The row is retained (audit) but excluded from default reads. Idempotent — deleting an already-deleted skill is a 204 no-op. Requires manage permission on the skill. - [Undelete a soft-deleted skill](https://docs.staging.getmodus.com/api-reference/skills/undelete-a-soft-deleted-skill.md): AIP-164. Restores a soft-deleted skill by clearing its tombstone flag and returns the resulting draft snapshot. Idempotent — undeleting an already-active skill returns the skill unchanged. Requires manage permission on the underlying row; a missing or cross-org id surfaces as 404 (existence is hidde… - [Update a skill (or re-parent under a new manager)](https://docs.staging.getmodus.com/api-reference/skills/update-a-skill-or-re-parent-under-a-new-manager.md): When the body contains `managerId`, the skill is re-parented under that manager (or detached if `managerId` is null). Otherwise, the supplied fields are written into the draft variation. Mixing `managerId` with other fields is rejected (422) — these are mutually exclusive operations. Edits to `acces… - [List LLM usage for the current org (SPA-only)](https://docs.staging.getmodus.com/api-reference/usage/list-llm-usage-for-the-current-org-spa-only.md): Returns time-bucketed LLM call counts and input/output tokens broken down by model. The query window is [since, until); `rollup` selects hour or day bucket size. Org scope is taken from the authenticated principal — there is no org_id query parameter. - [Delete all modus-side state for the active organization](https://docs.staging.getmodus.com/api-reference/users/delete-all-modus-side-state-for-the-active-organization.md): Hard-deletes all modus-side resources owned by the principal's active org: drops the tenant Postgres schema (agents, context, integrations, etc.) and removes the public.organizations row with FK cascades. Idempotent. Does NOT delete the Clerk org — the caller handles that separately. Requires `users… - [Authentication](https://docs.staging.getmodus.com/authentication.md): Authenticate Modus API requests with a bearer token. - [Modus API](https://docs.staging.getmodus.com/index.md): Programmatic access to skills, agents, context, and users in the Modus platform. ## OpenAPI Specs - [openapi](https://docs.staging.getmodus.com/api-reference/openapi.json)