# Omnara

- [The open-source managed agent platform](https://docs.omnara.com/introduction.md): A self-hostable alternative to Claude Managed Agents and OpenAI's Agents API. Run durable AI agents on any model and any machine.
- [Quickstart](https://docs.omnara.com/quickstart.md): Define an agent config, grant the resources, and launch an agent with the dashboard, the CLI, the REST API, or the TypeScript SDK
- [Concepts](https://docs.omnara.com/concepts.md): Key concepts to understand when using Omnara
- [Examples](https://docs.omnara.com/examples/overview.md): Agents you can deploy with one prompt, plus code samples for specific features
- [X signal agent](https://docs.omnara.com/examples/x-signal-agent.md): A daily digest of the X posts worth your time on any topic
- [Reddit signal agent](https://docs.omnara.com/examples/reddit-signal-agent.md): A daily digest of the Reddit threads worth your time on any topic
- [LinkedIn signal agent](https://docs.omnara.com/examples/linkedin-signal-agent.md): A daily digest of the LinkedIn posts worth your time on any topic
- [SEO audit agent](https://docs.omnara.com/examples/seo-audit-agent.md): Audits a web page for SEO, answer engines, and AI search citations, and delivers a PDF report
- [PostHog analytics agent](https://docs.omnara.com/examples/posthog-analytics-agent.md): A daily usage report from your PostHog project
- [SRE agent](https://docs.omnara.com/examples/sre-agent.md): A read-only production investigator for AWS, with optional code access
- [Coding agent in Slack](https://docs.omnara.com/examples/slack-coding-agent.md): Mention it in Slack, Discord, or on a GitHub pull request, and it fixes the issue and opens or updates a pull request
- [PR review agent](https://docs.omnara.com/examples/pr-review-agent.md): Reviews your GitHub pull requests against a checkout of the repository and leaves inline findings
- [Browser agent](https://docs.omnara.com/examples/browser-agent.md): A long-running agent that signs in to your web apps and works in a real browser, overnight if needed
- [Email agent](https://docs.omnara.com/examples/email-agent.md): An agent with its own email address that people can email, Cc, or @mention
- [Video generation agent](https://docs.omnara.com/examples/video-generation-agent.md): Short videos from a brief, built with Remotion and delivered as an MP4
- [Agents](https://docs.omnara.com/agents/overview.md): Launch agents, inspect them, cancel work, and archive
- [Configs & profiles](https://docs.omnara.com/agents/configuration.md): Define agents with YAML or JSON
- [Sending input](https://docs.omnara.com/events/sending-input.md): Deliver messages to a running agent
- [Streaming events](https://docs.omnara.com/events/streaming.md): Read the agent timeline
- [Webhook payloads](https://docs.omnara.com/events/webhooks.md): Event webhook bodies and generated SDK schemas
- [Approvals & questions](https://docs.omnara.com/events/interactions.md): Respond when an agent needs approval or an answer
- [Artifacts](https://docs.omnara.com/events/artifacts.md): View metadata and download files referenced in an agent's event log
- [Tools & permissions](https://docs.omnara.com/tools/permissions.md): Control which tools an agent can use and which calls require approval
- [Built-in tools](https://docs.omnara.com/tools/built-in.md): Use built-in tools for web search, commands, machines, integrations, and more
- [Custom tools](https://docs.omnara.com/tools/custom.md): Declare a tool the model can call, execute it in your own system, and post the result back
- [MCP servers](https://docs.omnara.com/tools/mcp.md): Connect MCP servers and configure their tools, permissions, and authentication
- [Skills](https://docs.omnara.com/tools/skills.md): Versioned packages of instructions and files that agents load on demand
- [Machines overview](https://docs.omnara.com/machines/overview.md): How agents get computers — BYO machines, pools, grants, and bindings
- [Connect a machine](https://docs.omnara.com/machines/connect.md): Register your own machine and grant it to projects
- [Machine pools](https://docs.omnara.com/machines/pools.md): On-demand machine capacity from Arker, Blaxel, boxd, CreateOS, Daytona, Freestyle, Modal, Tenki, or Unikraft Cloud
- [Sandbox providers](https://docs.omnara.com/machines/providers/overview.md): Compare the sandbox providers you can use with Omnara
- [Arker](https://docs.omnara.com/machines/providers/arker.md): Hyper-elastic, durable virtual machines for agents at extreme scale
- [Blaxel](https://docs.omnara.com/machines/providers/blaxel.md): Infrastructure for autonomous agents, with microVMs that resume in about 25 ms
- [boxd](https://docs.omnara.com/machines/providers/boxd.md): Composable computers for devs and agents, with a full computer in under 10 ms
- [CreateOS](https://docs.omnara.com/machines/providers/createos.md): Give every agent its own computer, a Firecracker microVM that boots in about 30 ms
- [Daytona](https://docs.omnara.com/machines/providers/daytona.md): Lightning-fast, isolated sandboxes for running AI-generated code
- [Freestyle](https://docs.omnara.com/machines/providers/freestyle.md): Full Linux VMs for AI agents, ready in about 65 ms
- [Modal](https://docs.omnara.com/machines/providers/modal.md): Trusted infrastructure for untrusted agents, at the scale they demand
- [Tenki](https://docs.omnara.com/machines/providers/tenki.md): Full Linux computers for your AI agents, running in under a second
- [Unikraft Cloud](https://docs.omnara.com/machines/providers/unikraft.md): The millisecond compute layer, with VM-grade isolation and scale to zero
- [Model providers](https://docs.omnara.com/organization/model-providers.md): Connect providers, configure models, and grant them to projects
- [Secrets](https://docs.omnara.com/organization/secrets.md): Store credentials securely, rotate their values, and share them with projects
- [Members & access](https://docs.omnara.com/organization/members.md): Manage organizations, projects, members, roles, and invitations
- [Integrations](https://docs.omnara.com/integrations/overview.md): Connect project-owned integrations, subscribe conversations, and choose tools and interaction handlers
- [Slack](https://docs.omnara.com/integrations/slack.md): Launch thread agents from mentions and select Slack tools, subscriptions and approvals
- [GitHub](https://docs.omnara.com/integrations/github.md): Give agents scoped pull-request tools and configure PR event routing
- [Discord](https://docs.omnara.com/integrations/discord.md): Connect your bot and choose messaging tools, subscriptions and approval destinations
- [API overview](https://docs.omnara.com/api/overview.md): How the API is organized, plus the conventions every endpoint shares
- [Authentication](https://docs.omnara.com/api/authentication.md): Personal and organization API keys, device login for CLIs, and token management
- [Custom integrations](https://docs.omnara.com/integrations/custom-integrations.md): Connect your own service using agent inputs, custom tools and interactions
- [List the authenticated user's personal access tokens](https://docs.omnara.com/api-reference/endpoints/users-and-api-keys/list-the-authenticated-users-personal-access-tokens.md): Items are ordered by created_at descending, then id descending.
- [Create personal access token](https://docs.omnara.com/api-reference/endpoints/users-and-api-keys/create-personal-access-token.md)
- [Revoke a personal access token](https://docs.omnara.com/api-reference/endpoints/users-and-api-keys/revoke-a-personal-access-token.md)
- [Get the authenticated user and their organizations](https://docs.omnara.com/api-reference/endpoints/users-and-api-keys/get-the-authenticated-user-and-their-organizations.md)
- [Delete the authenticated user's account](https://docs.omnara.com/api-reference/endpoints/users-and-api-keys/delete-the-authenticated-users-account.md): Deletes the account, revokes all personal access tokens and browser sessions, removes all organization and project memberships, and releases the account's sign-in identity (emails, linked auth identities, and password credentials) so the same email can register a new account. Personal secrets and sk…
- [List pending invitations](https://docs.omnara.com/api-reference/endpoints/users-and-api-keys/list-pending-invitations.md): Items are ordered by created_at ascending, then id ascending.
- [Accept invitation](https://docs.omnara.com/api-reference/endpoints/users-and-api-keys/accept-invitation.md)
- [Decline invitation](https://docs.omnara.com/api-reference/endpoints/users-and-api-keys/decline-invitation.md)
- [List org API keys](https://docs.omnara.com/api-reference/endpoints/users-and-api-keys/list-org-api-keys.md): Items are ordered by created_at descending, then id descending. Revoked keys are included.
- [Create org API key](https://docs.omnara.com/api-reference/endpoints/users-and-api-keys/create-org-api-key.md): Mints an org API key. The plaintext token is returned once and never stored.
- [Get an org API key](https://docs.omnara.com/api-reference/endpoints/users-and-api-keys/get-an-org-api-key.md)
- [Update an org API key](https://docs.omnara.com/api-reference/endpoints/users-and-api-keys/update-an-org-api-key.md): Renames the key and/or changes its org role. Revoked keys cannot be updated.
- [Revoke an org API key](https://docs.omnara.com/api-reference/endpoints/users-and-api-keys/revoke-an-org-api-key.md): Terminally revokes the key and removes its org and project roles. Idempotent.
- [List an org API key's explicit project role grants](https://docs.omnara.com/api-reference/endpoints/users-and-api-keys/list-an-org-api-keys-explicit-project-role-grants.md): Lists the key's explicit per-project role grants. Keys with the admin org role implicitly have admin access to every project and will not appear here for those projects.
- [Set an org API key's role on a project](https://docs.omnara.com/api-reference/endpoints/users-and-api-keys/set-an-org-api-keys-role-on-a-project.md): Creates or updates the key's explicit role grant on the project.
- [Remove an org API key's project role grant](https://docs.omnara.com/api-reference/endpoints/users-and-api-keys/remove-an-org-api-keys-project-role-grant.md)
- [List the authenticated principal's organizations](https://docs.omnara.com/api-reference/endpoints/organizations-and-projects/list-the-authenticated-principals-organizations.md): Users get every organization they belong to; org API keys get the organization that issued them. Items are ordered by organization name ascending.
- [Create organization](https://docs.omnara.com/api-reference/endpoints/organizations-and-projects/create-organization.md): Creates the organization and its local default resources atomically. An idempotency key determines the proposed organization ID; replaying it returns the existing organization. Without a key, each request is a fresh attempt. Optional default-provider provisioning begins after commit and retries asyn…
- [Delete organization](https://docs.omnara.com/api-reference/endpoints/organizations-and-projects/delete-organization.md): Deletes the organization and everything in it: projects, memberships, pending invitations, profiles, integrations, machine pools and machines, model provider configs and configured models, and all skills. Agents are archived and their runtimes and queued work are stopped. Secrets are permanently del…
- [Get org usage](https://docs.omnara.com/api-reference/endpoints/organizations-and-projects/get-org-usage.md): Tallies model token usage and provider-reported cost across every project the caller can read in the organization, broken down by configured model. Optionally limits the tally to a time window or to a subset of those projects; including a project the caller can't read is not found.
- [Get usage timeseries](https://docs.omnara.com/api-reference/endpoints/organizations-and-projects/get-usage-timeseries.md): Buckets model usage over time for one metric, optionally broken down by configured model or agent profile. Covers every project the caller can read in the organization; `project_ids` and `agent_profile_ids` narrow that scope. Buckets are calendar days, weeks (starting Monday), or months in `timezone…
- [List visible projects](https://docs.omnara.com/api-reference/endpoints/organizations-and-projects/list-visible-projects.md): Lists the projects the caller can access in the organization, newest first, with the caller's permissions on each.
- [Create project](https://docs.omnara.com/api-reference/endpoints/organizations-and-projects/create-project.md): Creates a project, makes the caller its admin, and returns it. The new project has no grants to organization models, machines, skills, or secrets.
- [Delete project](https://docs.omnara.com/api-reference/endpoints/organizations-and-projects/delete-project.md): Deletes the project, its memberships, profiles and profile versions, integrations and their interaction targets, project-owned skills and revisions, and grants owned by or targeting the project. Project-owned secrets are permanently deleted with their versions and grants. The project's agents are ar…
- [Get project usage](https://docs.omnara.com/api-reference/endpoints/organizations-and-projects/get-project-usage.md): Tallies model token usage and provider-reported cost across every agent in the project, including subagents, broken down by configured model. Optionally limits the tally to a time window.
- [List organization members](https://docs.omnara.com/api-reference/endpoints/organizations-and-projects/list-organization-members.md): List organization members with server-side display-name filtering, sorting, and cursor pagination.
- [Remove org member](https://docs.omnara.com/api-reference/endpoints/organizations-and-projects/remove-org-member.md): Removes the user's organization membership and all project memberships in the organization. The member's personal secrets and skills in the organization are deleted with the membership. Removal is blocked when the user is the organization's last owner, while a personal skill is referenced by an acti…
- [Update org member role](https://docs.omnara.com/api-reference/endpoints/organizations-and-projects/update-org-member-role.md)
- [List a member's explicit project role grants](https://docs.omnara.com/api-reference/endpoints/organizations-and-projects/list-a-members-explicit-project-role-grants.md): Lists the member's explicit per-project role grants. Org owners and admins implicitly have admin access to every project and will not appear here for those projects.
- [Set a member's role on a project](https://docs.omnara.com/api-reference/endpoints/organizations-and-projects/set-a-members-role-on-a-project.md): Creates or updates the member's explicit role grant on the project.
- [Remove a member's project role grant](https://docs.omnara.com/api-reference/endpoints/organizations-and-projects/remove-a-members-project-role-grant.md): Removes only the member's explicit role grant for this project. No other memberships, grants, or resources are deleted, and there are no dependency blockers.
- [List org invitations](https://docs.omnara.com/api-reference/endpoints/organizations-and-projects/list-org-invitations.md): Every listed invitation is pending: accepting, declining, revoking, or organization deletion removes the invitation. Items are ordered by created_at descending, then id descending.
- [Create org invitation](https://docs.omnara.com/api-reference/endpoints/organizations-and-projects/create-org-invitation.md)
- [Delete org invitation](https://docs.omnara.com/api-reference/endpoints/organizations-and-projects/delete-org-invitation.md): Deletes the pending invitation so it can no longer be accepted.
- [List agents across projects](https://docs.omnara.com/api-reference/endpoints/agents/list-agents-across-projects.md): Lists agents in every project of the organization where the caller can read agents. Each agent carries its project_id. Items are ordered by created_at descending, then id descending.
- [List agents](https://docs.omnara.com/api-reference/endpoints/agents/list-agents.md): Lists the project's agents with their current activity, newest first by default. Archived agents and subagents are excluded unless requested.
- [Create agent](https://docs.omnara.com/api-reference/endpoints/agents/create-agent.md): Launch from a pinned config, optionally adding agent-local integration tools, subscriptions and interaction handlers and admitting an attributed initial text input in the same transaction. Adding integration capabilities requires project management permission; launching an existing config requires a…
- [Get agent](https://docs.omnara.com/api-reference/endpoints/agents/get-agent.md): Returns one agent's state, model, profile, current config ID, activity (running, waiting_on_interaction, idle, or archived), attached machines, and MCP connection states. The conversation isn't included.
- [Get agent usage](https://docs.omnara.com/api-reference/endpoints/agents/get-agent-usage.md): Tallies this agent's model token usage and provider-reported cost, broken down by configured model. Optionally limits the tally to a time window.
- [Archive agent](https://docs.omnara.com/api-reference/endpoints/agents/archive-agent.md): Archives the agent: requests cancellation of its active runtime, cancels queued inputs and affected processes, removes its pending wakeup, releases explicit machine bindings, deletes pooled machines created for the agent, and deletes cron triggers targeting the agent. The agent and its full event hi…
- [Update agent config](https://docs.omnara.com/api-reference/endpoints/agents/update-agent-config.md): Replaces an active agent's config without restarting its conversation and returns the new agent_config. Model, instruction, and tool changes apply at the agent's next model call; machine changes apply immediately, stopping processes on removed machines and deleting the agent's machines from removed…
- [Create agent input](https://docs.omnara.com/api-reference/endpoints/agents/create-agent-input.md): Sends a message to an agent and returns the stored input. Queued messages (the default) wait until the agent is ready for new work; steering messages reach it at its next model call.
- [List tool calls](https://docs.omnara.com/api-reference/endpoints/agents/list-tool-calls.md): Items are ordered by created_at ascending, then id ascending.
- [Submit a result for a ready custom tool call](https://docs.omnara.com/api-reference/endpoints/agents/submit-a-result-for-a-ready-custom-tool-call.md): Only ready custom tool calls accept externally supplied results. The first accepted result completes the call. Any later submission, or a result for a non-custom tool call, returns 409.
- [Cancel agent](https://docs.omnara.com/api-reference/endpoints/agents/cancel-agent.md): Stops the agent's current turn: cancels its unfinished tool calls and open interactions, stops processes whose run_command hasn't returned yet, and discards pending steering messages. The agent stays active and keeps its queued messages, and processes whose run_command already returned keep running.…
- [List waiting backlog inputs](https://docs.omnara.com/api-reference/endpoints/agents/list-waiting-backlog-inputs.md): Steering inputs are listed first, followed by queued inputs. Each group is ordered by input rank, queued_at ascending, then id ascending.
- [Cancel queued backlog input](https://docs.omnara.com/api-reference/endpoints/agents/cancel-queued-backlog-input.md)
- [Move queued backlog input](https://docs.omnara.com/api-reference/endpoints/agents/move-queued-backlog-input.md)
- [Promote queued input to steering](https://docs.omnara.com/api-reference/endpoints/agents/promote-queued-input-to-steering.md)
- [Demote steering input to queued](https://docs.omnara.com/api-reference/endpoints/agents/demote-steering-input-to-queued.md)
- [List agent profiles across projects](https://docs.omnara.com/api-reference/endpoints/configs-and-profiles/list-agent-profiles-across-projects.md): Lists agent profiles in every project of the organization the caller can read. Each profile carries its project_id. Items are ordered by created_at descending, then id descending.
- [Resolve agent config tools](https://docs.omnara.com/api-reference/endpoints/configs-and-profiles/resolve-agent-config-tools.md): Returns configured built-in and custom tools plus missing machine, skill, subagent, and retrieval defaults, including disabled entries. Accepts YAML/JSON source. Source previews validate tool-related fields only; they do not validate whether the config can be saved or launched. Does not resolve cont…
- [Create agent config](https://docs.omnara.com/api-reference/endpoints/configs-and-profiles/create-agent-config.md): Compiles and saves an immutable agent config (instruction, model, tools, machine_sources, and more) from YAML or JSON and returns it. Sending the same source again returns the existing config, as long as its names still resolve to the same resources.
- [Get tool catalog](https://docs.omnara.com/api-reference/endpoints/configs-and-profiles/get-tool-catalog.md): Lists the built-in tools agent configs can use, with each tool's description and permission settings, plus the permission modes for custom and MCP tools.
- [Search the MCP server registry](https://docs.omnara.com/api-reference/endpoints/configs-and-profiles/search-the-mcp-server-registry.md): Search the API's snapshot of the public MCP registry. The snapshot only holds active servers that publish a `streamable-http` remote. Results are ranked by relevance when `q` is set, otherwise ordered by name.
- [List an MCP server's tools](https://docs.omnara.com/api-reference/endpoints/configs-and-profiles/list-an-mcp-servers-tools.md): Connects to a remote MCP server over streamable HTTP, negotiates the protocol version (stateless `server/discover` first, falling back to the `initialize` handshake for session-based servers), and returns the server's `tools/list` result. The request is not stored; use it to preview which tools a se…
- [Get agent config](https://docs.omnara.com/api-reference/endpoints/configs-and-profiles/get-agent-config.md): Returns one agent config: its compiled definition with names resolved to IDs, and its source if it was saved with one. Configs Omnara derives on its own, such as those for subagents and integration launches, have no source.
- [Get generated agent config source](https://docs.omnara.com/api-reference/endpoints/configs-and-profiles/get-generated-agent-config-source.md): Rebuilds a source from the config's compiled_definition, for configs saved without a source.
- [List agent profiles](https://docs.omnara.com/api-reference/endpoints/configs-and-profiles/list-agent-profiles.md): Lists the project's agent profiles, newest first by default, filterable by name. Items include a summary of each profile's current config, not its full compiled definition.
- [Create agent profile](https://docs.omnara.com/api-reference/endpoints/configs-and-profiles/create-agent-profile.md): Creates a named profile that points at an agent config and returns the profile with its current config.
- [Get agent profile](https://docs.omnara.com/api-reference/endpoints/configs-and-profiles/get-agent-profile.md): Returns one agent profile with its current config, current_config_id, and current_generation.
- [Delete agent profile](https://docs.omnara.com/api-reference/endpoints/configs-and-profiles/delete-agent-profile.md): Deletes the profile, all of its profile versions, and any cron triggers targeting the profile. Agents launched from the profile are retained and keep running: each agent holds an immutable snapshot of the configuration it was launched with, so its reference to the profile becomes historical provenan…
- [Rename agent profile](https://docs.omnara.com/api-reference/endpoints/configs-and-profiles/rename-agent-profile.md): Renames an agent profile without changing its config. Agents and cron triggers reference the profile by ID and keep working, but configs that name the profile under subagents must use the new name the next time they're compiled.
- [Get agent profile usage](https://docs.omnara.com/api-reference/endpoints/configs-and-profiles/get-agent-profile-usage.md): Tallies model token usage and provider-reported cost across the top-level agents launched from this profile, broken down by configured model. Usage from subagents those agents spawned is included only when `include_subagents` is true. Optionally limits the tally to a time window.
- [Update agent profile](https://docs.omnara.com/api-reference/endpoints/configs-and-profiles/update-agent-profile.md): Points a profile at a different agent config. Existing agents keep their current config; agents launched from the profile afterward use the new one. Fails with 409 unless expected_current_config_id matches the profile's current config.
- [List cron triggers](https://docs.omnara.com/api-reference/endpoints/configs-and-profiles/list-cron-triggers.md): Lists the project's cron triggers, newest first by default, filterable by name, agent, profile, or integration. Each item includes its schedule and next_fire_at.
- [Create cron trigger](https://docs.omnara.com/api-reference/endpoints/configs-and-profiles/create-cron-trigger.md): Creates a cron trigger that fires on a schedule. A trigger targeting an agent profile launches a new agent from the profile's current config on each firing; a trigger targeting an agent sends an input to that agent. Missed firings are coalesced, matching standard cron behavior: if one or more schedu…
- [Get cron trigger](https://docs.omnara.com/api-reference/endpoints/configs-and-profiles/get-cron-trigger.md): Returns one cron trigger: its target, schedule, timezone, message template, enabled flag, and firing state (last_fired_at, next_fire_at, and any failure since the last successful firing).
- [Delete cron trigger](https://docs.omnara.com/api-reference/endpoints/configs-and-profiles/delete-cron-trigger.md): Deletes a cron trigger so it never fires again; there is no undo. Agents it already launched keep running.
- [Update cron trigger](https://docs.omnara.com/api-reference/endpoints/configs-and-profiles/update-cron-trigger.md): Updates the schedule, message template, or enabled state. The target is immutable; delete the trigger and create a new one to retarget.
- [List skills visible through ownership authority](https://docs.omnara.com/api-reference/endpoints/skills/list-skills-visible-through-ownership-authority.md): Items are ordered by created_at descending, then id descending. Without an owner filter, returns the deduplicated union of organization skills the caller may list, project skills the caller may list, and the caller's own user skills. Grants are managed separately and do not change ownership.
- [Create skill](https://docs.omnara.com/api-reference/endpoints/skills/create-skill.md): Uploads a skill archive. If a skill with the archive's name already exists for the requested owner, the upload becomes the skill's next revision. The owner is immutable after creation.
- [Get skill through ownership authority](https://docs.omnara.com/api-reference/endpoints/skills/get-skill-through-ownership-authority.md): Returns one skill with its latest SKILL.md text and file listing.
- [Update skill by uploading a new revision](https://docs.omnara.com/api-reference/endpoints/skills/update-skill-by-uploading-a-new-revision.md): Creates the skill's next revision from either a replacement archive or replacement SKILL.md content (which keeps every other file from the current revision). The SKILL.md frontmatter `name` must match the skill's existing name.
- [Delete skill](https://docs.omnara.com/api-reference/endpoints/skills/delete-skill.md): Deletes the skill together with all of its revisions and project grants; uploaded archive content is destroyed. No other resources are deleted. Deletion is blocked while an active agent's configuration references the skill.
- [List skill grants](https://docs.omnara.com/api-reference/endpoints/skills/list-skill-grants.md): Lists the projects a skill is shared with, one grant per project, most recently shared first by default.
- [Create skill grant](https://docs.omnara.com/api-reference/endpoints/skills/create-skill-grant.md): Shares a skill with another project so its agent configs can attach it, and returns the grant; ownership doesn't change.
- [Delete skill grant](https://docs.omnara.com/api-reference/endpoints/skills/delete-skill-grant.md): Deletes only this project grant. The skill, its revisions, the target project, and other grants are retained, and there are no dependency blockers.
- [List skills available to project](https://docs.omnara.com/api-reference/endpoints/skills/list-skills-available-to-project.md): Includes directly owned project skills and granted skills, ordered by created_at descending, then id descending.
- [List memory stores across projects](https://docs.omnara.com/api-reference/endpoints/memory-stores/list-memory-stores-across-projects.md): Lists memory stores in every project of the organization the caller can read. Each store carries its project_id. Items are ordered by name, then id.
- [List memory stores](https://docs.omnara.com/api-reference/endpoints/memory-stores/list-memory-stores.md)
- [Create memory store](https://docs.omnara.com/api-reference/endpoints/memory-stores/create-memory-store.md)
- [Get memory store](https://docs.omnara.com/api-reference/endpoints/memory-stores/get-memory-store.md)
- [Delete memory store](https://docs.omnara.com/api-reference/endpoints/memory-stores/delete-memory-store.md)
- [Update memory store](https://docs.omnara.com/api-reference/endpoints/memory-stores/update-memory-store.md)
- [List memory files](https://docs.omnara.com/api-reference/endpoints/memory-stores/list-memory-files.md): List a directory's immediate children in name order. Omit path to list the store root.
- [Download memory file](https://docs.omnara.com/api-reference/endpoints/memory-stores/download-memory-file.md)
- [Write memory file](https://docs.omnara.com/api-reference/endpoints/memory-stores/write-memory-file.md)
- [Delete memory file](https://docs.omnara.com/api-reference/endpoints/memory-stores/delete-memory-file.md)
- [List secrets visible through ownership authority](https://docs.omnara.com/api-reference/endpoints/secrets/list-secrets-visible-through-ownership-authority.md): Items are ordered by created_at descending, then id descending. Without an owner filter, returns the deduplicated union of organization secrets the caller may list, project secrets the caller may list, and the caller's own user secrets.
- [Create secret](https://docs.omnara.com/api-reference/endpoints/secrets/create-secret.md): Creates an encrypted secret holding one credential and returns its metadata; the value is never returned. owner sets whether the organization, a project, or the caller owns it.
- [Start MCP OAuth for a new secret](https://docs.omnara.com/api-reference/endpoints/secrets/start-mcp-oauth-for-a-new-secret.md)
- [Get secret through ownership authority](https://docs.omnara.com/api-reference/endpoints/secrets/get-secret-through-ownership-authority.md): Returns a secret's owner, kind, name, and current version; the secret value is never returned.
- [Delete secret](https://docs.omnara.com/api-reference/endpoints/secrets/delete-secret.md): Deletes the secret and permanently destroys all of its versions and project grants; the ciphertext cannot be recovered. Deletion is blocked while the secret is the credential of a model provider config, machine pool, or integration.
- [Update secret metadata](https://docs.omnara.com/api-reference/endpoints/secrets/update-secret-metadata.md): Renames a secret or replaces its metadata, and returns the updated secret without its value. The value, kind, and owner can't be changed here. References use the secret ID, so renaming doesn't break them.
- [Create secret version](https://docs.omnara.com/api-reference/endpoints/secrets/create-secret-version.md)
- [List secret grants](https://docs.omnara.com/api-reference/endpoints/secrets/list-secret-grants.md): Lists the projects a secret is shared with, one grant per project, most recently shared first by default.
- [Create secret grant](https://docs.omnara.com/api-reference/endpoints/secrets/create-secret-grant.md): Shares a secret with another project so that project's resources can use it, and returns the grant; ownership doesn't change.
- [Delete secret grant](https://docs.omnara.com/api-reference/endpoints/secrets/delete-secret-grant.md): Deletes only this project grant. The secret, its versions, the target project, and other grants are retained, and there are no dependency blockers.
- [List secrets available to project](https://docs.omnara.com/api-reference/endpoints/secrets/list-secrets-available-to-project.md): Includes directly owned and granted secrets, ordered by created_at descending, then id descending.
- [Get secret available to project](https://docs.omnara.com/api-reference/endpoints/secrets/get-secret-available-to-project.md)
- [Connect an integration through OAuth](https://docs.omnara.com/api-reference/endpoints/integrations/connect-an-integration-through-oauth.md): Starts OAuth for this integration (currently Slack). The callback pins the integration and setup revision, records verified credentials, and returns integration_oauth=success and integration_id to the supplied local return_to route. It requires a browser session for the initiating user and current p…
- [Create a Slack provider app and connect it to an Omnara integration](https://docs.omnara.com/api-reference/endpoints/integrations/create-a-slack-provider-app-and-connect-it-to-an-omnara-integration.md): Creates a provider-side Slack app using the supplied configuration token, name and optional icon, then starts OAuth for this saved Omnara integration. The callback activates this integration only. It never creates another Omnara integration or changes launcher settings.
- [Start registration of a customer-owned GitHub App](https://docs.omnara.com/api-reference/endpoints/integrations/start-registration-of-a-customer-owned-github-app.md): Starts guided registration on github.com for a never-connected GitHub integration. Requires a browser session and project management access. Submit manifest as a JSON-encoded form field to registration_url. The callback saves a project credential secret and redirects to the canonical integration pag…
- [Inspect installations of a customer-owned GitHub App](https://docs.omnara.com/api-reference/endpoints/integrations/inspect-installations-of-a-customer-owned-github-app.md): Verifies the supplied project-available GitHub credential secret using App authentication and returns one bounded page of installations. Requires a browser session and project management access. Inspection does not connect or change this integration. Explicit confirmation uses ConfigureIntegration w…
- [List integrations across projects](https://docs.omnara.com/api-reference/endpoints/integrations/list-integrations-across-projects.md): Lists integrations in every project of the organization the caller can read. Each integration carries its project_id. Items are ordered by created_at descending, then id descending.
- [List project integrations](https://docs.omnara.com/api-reference/endpoints/integrations/list-project-integrations.md)
- [Create an integration and optional launcher](https://docs.omnara.com/api-reference/endpoints/integrations/create-an-integration-and-optional-launcher.md)
- [Get project integration](https://docs.omnara.com/api-reference/endpoints/integrations/get-project-integration.md)
- [Update integration settings](https://docs.omnara.com/api-reference/endpoints/integrations/update-integration-settings.md): Replaces integration-owned settings while preserving credentials. The request contains only settings; name and integration_kind are immutable and accepted only on create. Preserve integration-level fields when editing the launcher. Settings follow capabilities.settings.input_schema from the integrat…
- [Delete integration setup and revoke its capabilities](https://docs.omnara.com/api-reference/endpoints/integrations/delete-integration-setup-and-revoke-its-capabilities.md): Deletes the integration setup and its cron schedules, revokes its capabilities, and releases its credential reference. Existing agents, agent history, and provider messages are preserved.
- [List integration conversation subscriptions](https://docs.omnara.com/api-reference/endpoints/integrations/list-integration-conversation-subscriptions.md): Requires project read permission. Disconnected integrations retain their subscriptions and support listing.
- [Attach an agent to an integration conversation](https://docs.omnara.com/api-reference/endpoints/integrations/attach-an-agent-to-an-integration-conversation.md): Requires project management permission. Repeating an active attachment returns the same subscription. Subscriptions do not change the agent config or grant sending tools.
- [Stop forwarding an integration conversation to an agent](https://docs.omnara.com/api-reference/endpoints/integrations/stop-forwarding-an-integration-conversation-to-an-agent.md): Requires project management permission. Missing subscriptions are a no-op within an existing integration. Disconnected integrations support deletion. Stops future incoming forwarding for this subscription. The agent, sending tools, interaction handlers, and history remain available. Attaching the co…
- [Verify and configure integration credentials](https://docs.omnara.com/api-reference/endpoints/integrations/verify-and-configure-integration-credentials.md): Requires a user principal with project management permission. Slack credentials are configured through OAuth. A stale expected_setup_revision or a credential changed during verification returns 409; reload the integration and retry setup. Setup preserves integration settings; verified provider ident…
- [Disconnect this integration without deleting its configuration](https://docs.omnara.com/api-reference/endpoints/integrations/disconnect-this-integration-without-deleting-its-configuration.md)
- [List installed integration implementations and their capabilities](https://docs.omnara.com/api-reference/endpoints/integrations/list-installed-integration-implementations-and-their-capabilities.md)
- [List turns](https://docs.omnara.com/api-reference/endpoints/events/list-turns.md): Returns turns newest first. Use the returned next_before_turn_sequence as before_turn_sequence to fetch older turns.
- [List turn events](https://docs.omnara.com/api-reference/endpoints/events/list-turn-events.md): Returns one older event page for a turn, ordered chronologically within the page. Use the returned next_before_sequence as before_sequence to fetch older events.
- [List events](https://docs.omnara.com/api-reference/endpoints/events/list-events.md): Returns one page of agent events, chronological within the page. Forward pagination (after_sequence) walks from a known boundary toward the present using next_after_sequence. Backward pagination (before_sequence) starts at the latest events and walks toward the beginning using next_before_sequence;…
- [Stream events](https://docs.omnara.com/api-reference/endpoints/events/stream-events.md)
- [Get artifact](https://docs.omnara.com/api-reference/endpoints/events/get-artifact.md)
- [Get artifact content](https://docs.omnara.com/api-reference/endpoints/events/get-artifact-content.md)
- [List agent interactions](https://docs.omnara.com/api-reference/endpoints/interactions/list-agent-interactions.md): Lists an agent's permission prompts and ask_question questions, oldest first, with each one's form and answers. state filters by open, resolved, or canceled.
- [Resolve agent interaction](https://docs.omnara.com/api-reference/endpoints/interactions/resolve-agent-interaction.md): Answers an open permission prompt or question so the paused agent resumes, and returns the resolved interaction. Send one answer per question with zero-based option_indices; permission prompts use 0 for Allow and 1 for Deny.
- [List visible project machines](https://docs.omnara.com/api-reference/endpoints/machines/list-visible-project-machines.md): Items are ordered by machine created_at descending, then machine id descending.
- [List project machine grants](https://docs.omnara.com/api-reference/endpoints/machines/list-project-machine-grants.md): Lists explicit machine grants that can be deleted directly. Pool-derived machine access is managed through project machine pool grants.
- [Create project machine grant](https://docs.omnara.com/api-reference/endpoints/machines/create-project-machine-grant.md): Lets a project's agent configs use one BYO machine by name and returns the grant with the machine's record. Pooled machines can't be granted this way and return 404.
- [Delete project machine grant](https://docs.omnara.com/api-reference/endpoints/machines/delete-project-machine-grant.md): Removes the project's access to the machine. Processes that depended on the grant are stopped. The machine itself is retained, and there are no dependency blockers.
- [List visible machines](https://docs.omnara.com/api-reference/endpoints/machines/list-visible-machines.md): Lists the machines the caller can see, both BYO and pooled, newest first by default, with each one's connection state. Items are summaries without execution defaults or metadata.
- [Create machine](https://docs.omnara.com/api-reference/endpoints/machines/create-machine.md)
- [Connect a BYO machine](https://docs.omnara.com/api-reference/endpoints/machines/connect-a-byo-machine.md): Registers a machine you run yourself and returns its daemon token for installing omnarad on it; the token is shown only in this response. The machine stays offline until its daemon connects. project_ids grants it to those projects in the same call, and their agent configs reference it by display_nam…
- [Get machine](https://docs.omnara.com/api-reference/endpoints/machines/get-machine.md): Returns one active machine's full record: connection state, execution defaults (secret IDs only, never values), metadata, and the latest failure report. Machines in other lifecycle states, such as pool machines still provisioning, aren't returned.
- [Delete machine](https://docs.omnara.com/api-reference/endpoints/machines/delete-machine.md): Deletes a BYO machine, ends its active daemon runtimes and work, revokes its daemon tokens and project grants, and releases agent bindings. Pooled machines are managed through their machine pool and cannot be deleted through this route. There are no dependency blockers for a BYO machine.
- [Update machine execution defaults](https://docs.omnara.com/api-reference/endpoints/machines/update-machine-execution-defaults.md): Updates a machine's execution defaults: working directory, environment variables, and secret environment variables. env and secret_env replace the whole map, and changes apply to processes started afterward.
- [List byo machine daemon tokens](https://docs.omnara.com/api-reference/endpoints/machines/list-byo-machine-daemon-tokens.md): Items are ordered by created_at descending, then id descending.
- [Create byo machine daemon token](https://docs.omnara.com/api-reference/endpoints/machines/create-byo-machine-daemon-token.md)
- [Revoke machine daemon token](https://docs.omnara.com/api-reference/endpoints/machines/revoke-machine-daemon-token.md)
- [List project actors](https://docs.omnara.com/api-reference/endpoints/actors/list-project-actors.md): Items are ordered by created_at ascending, then id ascending.
- [Upsert an external actor](https://docs.omnara.com/api-reference/endpoints/actors/upsert-an-external-actor.md): Upserts by (provider_tenant_id, provider_user_id). Omitted attributes keep their stored values; provided attributes are overwritten, including empty values. An unchanged actor is not rewritten. Actors written through this endpoint always have the external provider.
- [Get a project actor](https://docs.omnara.com/api-reference/endpoints/actors/get-a-project-actor.md)
- [List model provider configs](https://docs.omnara.com/api-reference/endpoints/models/list-model-provider-configs.md): List model provider configs with server-side filtering, sorting, and cursor pagination.
- [Create model provider config](https://docs.omnara.com/api-reference/endpoints/models/create-model-provider-config.md): Create a model provider config, validate the configured credential where the provider exposes a validation endpoint, then probe the provider's /models endpoint. The result is returned as model_catalog; a failed probe does not fail creation.
- [Get model provider config](https://docs.omnara.com/api-reference/endpoints/models/get-model-provider-config.md): Returns one model provider config's stored settings; secret values are never returned. The provider isn't contacted, so the response doesn't list its models.
- [Update model provider config](https://docs.omnara.com/api-reference/endpoints/models/update-model-provider-config.md): Updates a model provider config's connection settings, such as its credential and headers, and returns the updated config; omitted fields keep their values. The credential secret is checked to exist and match auth_kind, but the provider isn't contacted, so a credential the provider rejects isn't cau…
- [Delete model provider config](https://docs.omnara.com/api-reference/endpoints/models/delete-model-provider-config.md): Deletes only the model provider config. Deletion is blocked while it has configured models. Cluster-managed provider configs cannot be deleted through this route.
- [Get model catalog](https://docs.omnara.com/api-reference/endpoints/models/get-model-catalog.md): Fetches the provider's live model catalog by validating the configured credential and probing the provider's /models endpoint. The call waits on the upstream provider, so it is slower than the other model provider config routes and can report failure as data.
- [List configured models](https://docs.omnara.com/api-reference/endpoints/models/list-configured-models.md): Lists the models configured under one model provider config, newest first, with each model's slug, token limits, and reasoning support.
- [Create configured model](https://docs.omnara.com/api-reference/endpoints/models/create-configured-model.md): Adds a provider model to this provider config under the name agent configs use as model.name, and returns it. The model slug isn't checked against the provider's catalog, and no project can use the model yet.
- [Update configured model](https://docs.omnara.com/api-reference/endpoints/models/update-configured-model.md): Updates a configured model's settings and returns the updated model; omitted fields keep their values. Agents already using the model pick up the change on their next model call. The update isn't checked against project grants or agent configs, so lowering a limit below their overrides or turning of…
- [Delete configured model](https://docs.omnara.com/api-reference/endpoints/models/delete-configured-model.md): Deletes only the configured model. Deletion is blocked while it has active project grants. Cluster-managed configured models cannot be deleted through this route.
- [List project model grants](https://docs.omnara.com/api-reference/endpoints/models/list-project-model-grants.md): Lists the configured models a project can use, most recently granted first by default, with each grant's overrides and the model's name and provider config.
- [Create project model grant](https://docs.omnara.com/api-reference/endpoints/models/create-project-model-grant.md): Lets a project's agent configs use a configured model and returns the new grant. Optional overrides can narrow the model for that project (lower token limits, tools or reasoning turned off, fewer reasoning efforts or modalities) and set its per-request defaults within those limits.
- [Delete project model grant](https://docs.omnara.com/api-reference/endpoints/models/delete-project-model-grant.md): Removes the project's access to the configured model. The grant is live policy: new launches can no longer select the model, and agents already using it lose access on their next model call. The model itself is retained, and there are no dependency blockers.
- [Update project model grant](https://docs.omnara.com/api-reference/endpoints/models/update-project-model-grant.md): Updates the project's overrides for the configured model. Omitted fields keep their current values; null, or [] for supported_reasoning_efforts, input_modalities, and output_modalities, clears an override so the project inherits from the configured model. Agents already using the model apply the upd…
- [List machine pools](https://docs.omnara.com/api-reference/endpoints/machine-pools/list-machine-pools.md): List machine pools with server-side filtering, sorting, and cursor pagination.
- [Create machine pool](https://docs.omnara.com/api-reference/endpoints/machine-pools/create-machine-pool.md)
- [Check machine pool connection](https://docs.omnara.com/api-reference/endpoints/machine-pools/check-machine-pool-connection.md): Checks a tenant-managed pool's provider credential and provider config by making read-only requests to the provider.
- [Get machine pool](https://docs.omnara.com/api-reference/endpoints/machine-pools/get-machine-pool.md): Returns one machine pool's configuration and current usage: provider, default machine settings, CPU, memory, and machine-count limits, and idle deletion policy.
- [Update machine pool](https://docs.omnara.com/api-reference/endpoints/machine-pools/update-machine-pool.md): Tenant-managed pools support every request field. Cluster-managed pools only allow changes to default CPU and memory, environment and secret environment variables, provider-supported per-machine CPU and memory limits, and the idle deletion policy. Other cluster-managed changes are rejected with 409…
- [Delete machine pool](https://docs.omnara.com/api-reference/endpoints/machine-pools/delete-machine-pool.md): Deletes the machine pool and its pooled machines, revokes generated machine grants and project machine-pool grants, and stops processes that depended on those grants. Deleting a cluster-managed machine pool is rejected with 409 Conflict; there are no other dependency blockers.
- [List project machine pool grants](https://docs.omnara.com/api-reference/endpoints/machine-pools/list-project-machine-pool-grants.md): Lists the machine pools a project can create machines from, one grant per pool, most recently granted first by default.
- [Create project machine pool grant](https://docs.omnara.com/api-reference/endpoints/machine-pools/create-project-machine-pool-grant.md): Lets a project create machines from a machine pool, optionally with its own defaults and usage caps within the pool's limits, and returns the grant. No machines are created by this call.
- [Get project machine pool grant](https://docs.omnara.com/api-reference/endpoints/machine-pools/get-project-machine-pool-grant.md): Returns one project's grant for a machine pool, with the defaults and limits it sets on top of the pool's own. Null fields set no override, so the pool's value applies.
- [Delete project machine pool grant](https://docs.omnara.com/api-reference/endpoints/machine-pools/delete-project-machine-pool-grant.md): Removes the project's access to the machine pool, revokes machine grants generated through it, and stops processes that depended on those grants. The pool itself is retained, and there are no dependency blockers.
- [Update project machine pool grant](https://docs.omnara.com/api-reference/endpoints/machine-pools/update-project-machine-pool-grant.md): Updates the grant's overrides and limits. Omitted fields keep their current values; null clears an override so the grant follows the machine pool again. Overlay objects and metadata are replaced whole when present. Existing machines keep their configuration; the updated defaults and limits apply to…
- [Changelog](https://docs.omnara.com/changelog.md): New features, improvements, and fixes in Omnara

## OpenAPI Specs

- [openapi](/api-reference/openapi.yaml)

## Optional

- [Discord](https://discord.gg/Dc46sYk6e3)


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