# Matrices

> Build, configure, and operate long-lived agents through the Matrices API.

- [Welcome to Matrices](https://docs.matrices.com/index.md)
- [Quickstart](https://docs.matrices.com/quickstart.md)
- [System Architecture](https://docs.matrices.com/model/how-it-fits-together.md)
- [Workspaces](https://docs.matrices.com/model/workspaces.md): The tenant boundary.
- [Identities](https://docs.matrices.com/model/identities.md): Who an agent acts for.
- [Roles](https://docs.matrices.com/model/roles.md): Named bundles of tool access.
- [Toolsets](https://docs.matrices.com/model/toolsets.md): Your own tools, under one namespace.
- [Connections](https://docs.matrices.com/model/connections.md): Credentials the model never sees.
- [Profiles](https://docs.matrices.com/model/profiles.md): Behavior you define once and share.
- [Hooks](https://docs.matrices.com/model/hooks.md): Approve, deny, or rewrite work mid-turn.
- [Agents](https://docs.matrices.com/model/agents.md): The long-lived thing you talk to.
- [Threads](https://docs.matrices.com/model/threads.md): One conversation, and its full log.
- [Memory](https://docs.matrices.com/model/memory.md): What an agent keeps between threads.
- [Schedules](https://docs.matrices.com/model/schedules.md): Work that starts without you.
- [Feeds](https://docs.matrices.com/model/feeds.md): How agents talk to each other.
- [Rules](https://docs.matrices.com/model/rules.md): Things that always hold.
- [Build your first agent](https://docs.matrices.com/guides/first-agent.md): A role, a profile, an identity, and a first thread.
- [Narrow an agent's permissions](https://docs.matrices.com/guides/narrow-permissions.md): Allow one tool for reads only, and take a whole family away.
- [Connect a service](https://docs.matrices.com/guides/connect-a-service.md): Give an agent a Linear login the model never gets to read.
- [Approve a tool call](https://docs.matrices.com/guides/approve-a-tool-call.md): Hold a write until a human says yes.
- [Run on a schedule](https://docs.matrices.com/guides/run-on-a-schedule.md): Send an agent a message later, or every morning.
- [Wire up a small team](https://docs.matrices.com/guides/agent-team.md): One agent publishes, another one wakes up and reviews it.
- [Built-in tools](https://docs.matrices.com/reference/built-in-tools.md): Every tool an agent gets without registering a toolset.
- [Thread events](https://docs.matrices.com/reference/thread-events.md): Every event type, status, and content block a thread can produce.
- [Permissions](https://docs.matrices.com/reference/permissions.md): Selector grammar, condition operators, and the stacking rules.
- [Hooks](https://docs.matrices.com/reference/hooks.md): Points, processors, decisions, and the default approval set.
- [Models](https://docs.matrices.com/reference/models.md): Catalog fields, selector grammar, and what a turn pins.
- [Limits](https://docs.matrices.com/reference/limits.md): Every number the API enforces, in one place.
- [Changelog](https://docs.matrices.com/changelog.md): Product and API updates for Matrices.
- [Self-hosting](https://docs.matrices.com/self-hosting.md): Run the Matrices data plane inside your own VPC.
- [API Reference](https://docs.matrices.com/api-reference/overview.md): The overview of the Matrices API.
- [Get auth context](https://docs.matrices.com/api-reference/auth/get-auth-context.md)
- [List workspace identities](https://docs.matrices.com/api-reference/identities/list-workspace-identities.md)
- [Disable an identity](https://docs.matrices.com/api-reference/identities/disable-an-identity.md): Idempotently refuses new work and credential issuance for one materialized workspace identity.
- [Enable an identity](https://docs.matrices.com/api-reference/identities/enable-an-identity.md): Idempotently restores new work and credential issuance for one materialized workspace identity.
- [List connections](https://docs.matrices.com/api-reference/connections/list-connections.md): Returns a cursor page of safe connection metadata. Credential material is never returned. When status is omitted, revoked tombstones are excluded; pass status=revoked to retrieve them explicitly.
- [Create a token connection](https://docs.matrices.com/api-reference/connections/create-a-token-connection.md): Encrypts a one-way token write and returns only safe connection metadata.
- [Get a connection](https://docs.matrices.com/api-reference/connections/get-a-connection.md): Returns safe connection metadata without credential material.
- [Replace a connection token](https://docs.matrices.com/api-reference/connections/replace-a-connection-token.md): Optimistically replaces the encrypted token. The token is a one-way write.
- [Revoke a connection](https://docs.matrices.com/api-reference/connections/revoke-a-connection.md): Atomically disables local issuance and destroys encrypted credential material before one best-effort remote revocation attempt. API-key and user principals must send the current positive expectedVersion. Agent principals must send an empty object and an Idempotency-Key; platform derives the active c…
- [List profiles](https://docs.matrices.com/api-reference/profiles/list-profiles.md)
- [Create a profile](https://docs.matrices.com/api-reference/profiles/create-a-profile.md)
- [Get a profile](https://docs.matrices.com/api-reference/profiles/get-a-profile.md)
- [Update a profile](https://docs.matrices.com/api-reference/profiles/update-a-profile.md)
- [Delete a profile](https://docs.matrices.com/api-reference/profiles/delete-a-profile.md)
- [List agents](https://docs.matrices.com/api-reference/agents/list-agents.md)
- [Create an agent](https://docs.matrices.com/api-reference/agents/create-an-agent.md)
- [Get an agent](https://docs.matrices.com/api-reference/agents/get-an-agent.md)
- [Update an agent](https://docs.matrices.com/api-reference/agents/update-an-agent.md)
- [Delete an agent](https://docs.matrices.com/api-reference/agents/delete-an-agent.md)
- [Get an agent's effective permissions](https://docs.matrices.com/api-reference/agents/get-an-agents-effective-permissions.md): Returns the bounded effective tool inventory and conditional grants for one agent. Broker credentials and transport-only fields are omitted.
- [List schedules for an agent](https://docs.matrices.com/api-reference/schedules/list-schedules-for-an-agent.md)
- [Create a schedule](https://docs.matrices.com/api-reference/schedules/create-a-schedule.md)
- [Get a schedule](https://docs.matrices.com/api-reference/schedules/get-a-schedule.md)
- [Update a schedule](https://docs.matrices.com/api-reference/schedules/update-a-schedule.md)
- [Delete a schedule](https://docs.matrices.com/api-reference/schedules/delete-a-schedule.md)
- [List roles](https://docs.matrices.com/api-reference/roles/list-roles.md)
- [Create a role](https://docs.matrices.com/api-reference/roles/create-a-role.md)
- [Get a role](https://docs.matrices.com/api-reference/roles/get-a-role.md)
- [Update a role](https://docs.matrices.com/api-reference/roles/update-a-role.md)
- [Delete a role](https://docs.matrices.com/api-reference/roles/delete-a-role.md)
- [List toolsets](https://docs.matrices.com/api-reference/toolsets/list-toolsets.md)
- [Create a toolset](https://docs.matrices.com/api-reference/toolsets/create-a-toolset.md)
- [Get a toolset](https://docs.matrices.com/api-reference/toolsets/get-a-toolset.md)
- [Update a toolset](https://docs.matrices.com/api-reference/toolsets/update-a-toolset.md)
- [Delete a toolset](https://docs.matrices.com/api-reference/toolsets/delete-a-toolset.md)
- [Recheck a remote MCP toolset's authentication](https://docs.matrices.com/api-reference/toolsets/recheck-a-remote-mcp-toolsets-authentication.md)
- [Get a remote MCP toolset's OAuth client configuration](https://docs.matrices.com/api-reference/toolsets/get-a-remote-mcp-toolsets-oauth-client-configuration.md)
- [Create or rotate a remote MCP toolset's OAuth client](https://docs.matrices.com/api-reference/toolsets/create-or-rotate-a-remote-mcp-toolsets-oauth-client.md)
- [Delete a remote MCP toolset's OAuth client](https://docs.matrices.com/api-reference/toolsets/delete-a-remote-mcp-toolsets-oauth-client.md)
- [List public model targets](https://docs.matrices.com/api-reference/models/list-public-model-targets.md): Returns targets in platform selection-precedence order. Changing the first target can change the default for every broad wildcard profile.
- [List models available to an agent](https://docs.matrices.com/api-reference/models/list-models-available-to-an-agent.md): Projects the agent profile's selectors against current platform precedence and returns only concrete catalog targets.
- [List threads for an agent](https://docs.matrices.com/api-reference/threads/list-threads-for-an-agent.md)
- [Create a thread](https://docs.matrices.com/api-reference/threads/create-a-thread.md)
- [List workspace threads](https://docs.matrices.com/api-reference/threads/list-workspace-threads.md)
- [Get a thread](https://docs.matrices.com/api-reference/threads/get-a-thread.md)
- [Cancel active and queued thread work](https://docs.matrices.com/api-reference/threads/cancel-active-and-queued-thread-work.md)
- [Get a turn snapshot](https://docs.matrices.com/api-reference/threads/get-a-turn-snapshot.md)
- [Get a turn result](https://docs.matrices.com/api-reference/threads/get-a-turn-result.md)
- [List workspace memory](https://docs.matrices.com/api-reference/memory/list-workspace-memory.md): Returns one cursor page from the authenticated workspace's shared namespace.
- [Get a workspace memory entry](https://docs.matrices.com/api-reference/memory/get-a-workspace-memory-entry.md)
- [Create or replace a workspace memory entry](https://docs.matrices.com/api-reference/memory/create-or-replace-a-workspace-memory-entry.md): Uses required compare-and-set semantics. Empty expectedVersion or "0" creates only when absent.
- [Delete a workspace memory entry](https://docs.matrices.com/api-reference/memory/delete-a-workspace-memory-entry.md): An unconditional delete succeeds for a missing entry. A delete with expectedVersion is compare-and-set and returns 404 when the entry is already absent.
- [List an agent's memory](https://docs.matrices.com/api-reference/memory/list-an-agents-memory.md): Returns one cursor page from the authenticated workspace's namespace for this agent.
- [Get an agent memory entry](https://docs.matrices.com/api-reference/memory/get-an-agent-memory-entry.md)
- [Create or replace an agent memory entry](https://docs.matrices.com/api-reference/memory/create-or-replace-an-agent-memory-entry.md): Uses required compare-and-set semantics. Empty expectedVersion or "0" creates only when absent.
- [Delete an agent memory entry](https://docs.matrices.com/api-reference/memory/delete-an-agent-memory-entry.md): An unconditional delete succeeds for a missing entry. A delete with expectedVersion is compare-and-set and returns 404 when the entry is already absent.
- [Create a private image upload](https://docs.matrices.com/api-reference/images/create-a-private-image-upload.md): Creates a short-lived grant for one direct object-store PUT. The PUT body must contain exactly image.size bytes and send every returned header unchanged; browser File and Blob bodies derive the signed Content-Length automatically. The URL is a bearer and must not be logged, persisted, or shared. A g…
- [Create private image downloads](https://docs.matrices.com/api-reference/images/create-private-image-downloads.md): Issues fresh short-lived private GET URLs for up to 20 image IDs. Missing and out-of-scope images are returned as indistinguishable unavailable entries while valid siblings still succeed.
- [List feeds](https://docs.matrices.com/api-reference/feeds/list-feeds.md): Returns active feeds by default. `query` searches names, descriptions, and tags. Filters combine with AND. Set `includeArchived=true` to include archived feeds.
- [Create a feed](https://docs.matrices.com/api-reference/feeds/create-a-feed.md)
- [Get a feed](https://docs.matrices.com/api-reference/feeds/get-a-feed.md)
- [Archive a feed](https://docs.matrices.com/api-reference/feeds/archive-a-feed.md)
- [List feed messages](https://docs.matrices.com/api-reference/feeds/list-feed-messages.md)
- [Append feed messages](https://docs.matrices.com/api-reference/feeds/append-feed-messages.md)
- [List subscriptions for an agent](https://docs.matrices.com/api-reference/subscriptions/list-subscriptions-for-an-agent.md)
- [Create a subscription](https://docs.matrices.com/api-reference/subscriptions/create-a-subscription.md)
- [Get a subscription](https://docs.matrices.com/api-reference/subscriptions/get-a-subscription.md)
- [Update a subscription](https://docs.matrices.com/api-reference/subscriptions/update-a-subscription.md)
- [Delete a subscription](https://docs.matrices.com/api-reference/subscriptions/delete-a-subscription.md)
- [List subscription evaluations](https://docs.matrices.com/api-reference/subscriptions/list-subscription-evaluations.md)
- [Append a message to a thread](https://docs.matrices.com/api-reference/messages/append-a-message-to-a-thread.md)
- [List pending thread messages](https://docs.matrices.com/api-reference/messages/list-pending-thread-messages.md): Returns the full pending set as a bare array, mirroring `ThreadView.queued`. The set is small by construction — queued messages are capped per thread at admission and steered messages drain into the next model sample — so this endpoint intentionally skips the limit/cursor envelope the event and wait…
- [Edit a pending thread message](https://docs.matrices.com/api-reference/messages/edit-a-pending-thread-message.md)
- [Cancel a pending thread message](https://docs.matrices.com/api-reference/messages/cancel-a-pending-thread-message.md)
- [List thread events](https://docs.matrices.com/api-reference/events/list-thread-events.md)
- [Stream thread activity events](https://docs.matrices.com/api-reference/events/stream-thread-activity-events.md)
- [Stream agent activity events](https://docs.matrices.com/api-reference/events/stream-agent-activity-events.md)
- [Stream workspace activity events](https://docs.matrices.com/api-reference/events/stream-workspace-activity-events.md)
- [List pending client tool calls](https://docs.matrices.com/api-reference/tools/list-pending-client-tool-calls.md): Returns a workspace-scoped work queue of pending client-executed tool calls. The v1 endpoint only accepts `status=pending`; use the cursor to continue scanning by wait creation time.
- [Submit a client tool result](https://docs.matrices.com/api-reference/tools/submit-a-client-tool-result.md): Delivers the output or model-visible error for a pending client-executed tool call. A 200 response means the result was durably accepted by the runtime; the turn may consume it asynchronously. Error reasons are shown to the model as tool failure text and are not rewritten by after_tool_result hooks.
- [Resolve a wait](https://docs.matrices.com/api-reference/hooks/resolve-a-wait.md): Resolves a human, async hook, or client hook wait with an allow or deny decision.

## OpenAPI Specs

- [platform.v1](/openapi/platform.v1.json)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.