Build with Completion

Your first Session

Use the Python SDK supplied with your environment. Set COMPLETION_API_ORIGIN to https://api.withcompletion.com (or your development API URL) and COMPLETION_API_KEY to an authorized bearer secret. The environment must have Agent execution and its model credentials configured.

Create an Agent, allocate a Session, then send a message. Creating either resource allocates it; sending the message submits the work. Each request below waits for the previous request to succeed.

import os
from uuid import uuid4

from completion_sdk import CompletionClient

agent_id = str(uuid4())
session_id = str(uuid4())
message_id = str(uuid4())

with CompletionClient(
    os.environ["COMPLETION_API_ORIGIN"],
    headers={
        "Authorization": f"Bearer {os.environ['COMPLETION_API_KEY']}"
    },
    timeout=120.0,
) as client:
    agent = client.create_agent(
        id=agent_id,
        title="Operations assistant",
        settings={"instructions": "Give clear, concise answers."},
    )
    if agent.status_code not in (200, 201):
        raise RuntimeError(agent.data)

    session = client.create_agent_session(
        agent_id=agent_id, id=session_id
    )
    if session.status_code not in (200, 201):
        raise RuntimeError(session.data)

    receipt = client.create_agent_message(
        agent_id=agent_id,
        session_id=session_id,
        id=message_id,
        content="Help me write a checklist for a new customer onboarding.",
    )
    print(receipt.status_code, receipt.data)
    if receipt.status_code != 202:
        raise RuntimeError(receipt.data)

    with client.stream_agent_session(
        id=agent_id, session_id=session_id
    ) as stream:
        for line in stream.iter_lines():
            print(line)

The message response acknowledges admission. The stream carries newline-delimited native Agent events, starting with a snapshot. An accepted message does not mean the Agent has finished. Use Session events to read committed history.

Keep the generated IDs if you need to repeat an immutable request. Reusing an ID with different input can return 409. A new task needs a new message ID.

Create AgentCreate SessionSend messageStream output

Authentication

Server integrations send an API secret in the Authorization: Bearer header. Browser sessions use an HTTP-only session cookie and select an Organization with X-Organization-ID. API keys already belong to one Organization and cannot select another.

GET /agents?limit=50 HTTP/1.1
Host: YOUR_API_HOST
Authorization: Bearer YOUR_API_SECRET

An API key has an explicit resource and operation scope. Every request must fit both that scope and its owner's current permissions. A key does not gain authority when the owner loses membership or resource access.

Create a key

Generate the secret locally, keep it private, and register its lowercase SHA-256 hash with a UUID and native_scope. Registration never returns the original secret or its hash. Choose only the operations your integration needs; an empty resource list grants none. Store the secret in your application's secret store.

Use PUT /api-keys/{id} to assign the supplied scope fields and DELETE /api-keys/{id} to revoke the key. Optional expiry uses an RFC 3339 timestamp.

Register keyUpdate scopeRevoke key

Agents & Sessions

An Agent holds the program and defaults for a worker. Its settings include instructions, model, reasoning effort, plugins, tools, skills, MCP servers, and optional voice settings. Selecting a capability does not grant permission to use its resources.

Create an Agent from a published Agent Template or with its own settings. You can select an existing Computer or Browser, or a Template for that resource. Select one source for each resource.

Allocate a Session

A Session belongs to one Agent and binds to a namespace at creation. Omitted resource selections inherit the Agent or parent Session selection. Explicit selections require your authority. The namespace binding stays fixed.

Session settings are saved at allocation. Later Agent edits do not rewrite existing Sessions. Use the Session settings operation to change the supplied behavior fields for that Session.

Send and observe work

create_agent_message sends input to an existing Session. It does not create a Session or change its selections. Live output uses NDJSON; committed history uses cursor pagination. Opening the stream before the Session has admitted input returns 409.

Closing an output stream stops observation while accepted work continues. Tool activity, assistant text, and the final reply are different events. Keep them distinct in your application.

Agent settingsSession settingsList Sessions

Programs & tools

An Agent's program contains its instructions, configuration, authored capabilities, and skills. Programs live in the filesystem. Settings operations edit the declared behavior fields while preserving other program files.

Skills describe how to perform a task and can include supporting resources. Tools provide actions. Your application owns its business data and permissions and can expose those actions through an MCP server.

Connect MCP servers

Declare remote MCP connections in the Agent's mcp.json. The connection list shows authorization state. For a connection that needs OAuth, request an authorization URL and complete the provider's consent flow. Disconnecting removes that connection's authorization.

List the remote tool catalog for an Agent before calling a tool. Tool calls return the native MCP result. A connection routed through a Computer also requires Computer use permission. Configured Vault placeholders require current permission to use the referenced secret.

Keep service credentials out of instructions, skills, and tool arguments. Use Vault references and the connection's authorized credential path.

ConnectionsAuthorize connectionDiscover toolsCall tool

Completion MCP

Connect Completion to any MCP client that supports Streamable HTTP and bearer authentication. The production endpoint is https://api.withcompletion.com/mcp. For local development, use your configured development API origin followed by /mcp.

Connect any MCP client

Choose a remote HTTP server in your client, paste the URL, and supply a scoped Completion API key as an Authorization header. No local MCP package or proxy is required.

{
  "url": "https://api.withcompletion.com/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_COMPLETION_API_KEY"
  }
}

The API key selects its Organization. An optional X-Organization-ID header must match it. Browser cookies and device credentials do not authenticate this endpoint. Clients need a way to supply bearer headers; this endpoint currently uses API keys.

These examples use the same endpoint and tools. Set COMPLETION_API_KEY in the environment of the client you launch, or use your client’s secret-input prompt.

{
  "mcpServers": {
    "completion": {
      "url": "https://api.withcompletion.com/mcp",
      "headers": {
        "Authorization": "Bearer ${env:COMPLETION_API_KEY}"
      }
    }
  }
}

{
  "mcpServers": {
    "completion": {
      "type": "http",
      "url": "https://api.withcompletion.com/mcp",
      "headers": {
        "Authorization": "Bearer ${COMPLETION_API_KEY}"
      }
    }
  }
}

{
  "inputs": [
    {
      "id": "completion_api_key",
      "type": "promptString",
      "description": "Completion API key",
      "password": true
    }
  ],
  "servers": {
    "completion": {
      "type": "http",
      "url": "https://api.withcompletion.com/mcp",
      "headers": {
        "Authorization": "Bearer ${input:completion_api_key}"
      }
    }
  }
}

[mcp_servers.completion]
url = "https://api.withcompletion.com/mcp"
bearer_token_env_var = "COMPLETION_API_KEY"

Available tools

The first catalog includes Agent creation, listing and reading; Session creation, listing and reading; Session settings reading and updating; message submission; and persisted event listing. Tool names use the Python SDK’s snake_case operation names. Arguments are top-level fields: for example, create_agent_session takes agent_id and a new Session id.

Each tool returns {"status_code": ..., "data": ...}. An HTTP error marks the MCP result as an error. A 202 message receipt means the work was admitted; read the Session’s persisted events to follow its output. The MCP catalog does not expose streams, secret writes, credential management, or action-review decisions.

Tool availability does not grant permission. API keys currently name existing authorized resources, so an external key cannot allocate a fresh Agent. Create the Agent through your authorized browser/API flow, then scope a key to that Agent and its namespace for Session work. A namespace uses /namespaces/{namespace_id} for filesystem permissions.

Connect a Completion Agent

Add Completion to the Agent’s mcp.json, using its configured public API origin. Omit credential headers and Computer selection for this connection.

{
  "mcpServers": {
    "completion": {
      "url": "https://api.withcompletion.com/mcp"
    }
  }
}

The Agent uses its native Code Mode remote_mcp tool to discover and call Completion. The server recognizes its own exact configured endpoint and connects in process. It retains the original caller’s credential reference, checks current membership and credential validity, and intersects current authority with the accepted input and saved Session scopes. No shared service key is delegated to the Agent.

Settings updates preserve omitted fields. Supplied arrays replace them; [], false, and "" retain their API meanings. Explicit null is accepted only where the API schema allows it.

Computers

A Computer is a managed environment or an attached device that an authorized caller can use for commands, terminal access, SSH, and desktop work. Agents select Computers separately from their own program and conversation.

Create a managed Computer

Choose one source: a native provider and its image selection, an authorized source Computer, or a Computer Template. The current contract names E2B, Daytona, Modal, Boat, Vercel, and Archil. Availability and capture support depend on the configured provider.

Fresh provider creation can use the environment's configured connection. Customer connections use exact Vault version references in credential_references. Copying from a Computer or Template retains its provider binding; it does not move the environment to another provider account.

Use and maintain it

Run Bash commands with execute_computer_command, open an interactive terminal, register a public SSH key, or start desktop access. Terminal and desktop streams use their declared native transports. Use SSH, SFTP, SCP, or commands for Computer files.

Pause and copy behavior follows provider capabilities. Copies prefer memory capture when the provider advertises it; otherwise they use disk snapshots. A failed memory capture remains an error. Software update operations inspect and apply the selected Computer release.

Attach an existing device

The pairing operations create a pairing request, look up its code, approve it, and connect the device. The connection establishes the device identity. Keep pairing codes and device credentials private, and use the installer and origin selected for your environment.

Create ComputerRun commandTerminalPair device

Browsers

A Browser is an independent, durable browser profile. Select it on an Agent or Session to give browser work its own resource and permissions.

The current public creation path allocates a fresh Kernel profile with provider: "kernel". It does not start a live browser. Existing profile import and Browser Template instantiation currently return 422; a native provider ID alone does not grant Completion access.

Live browser actions run through the Agent's native tools. Private fills use Vault references restricted to the exact HTTPS page destination. Manage the profile's metadata and owner through the public Browser operations.

Create BrowserRead BrowserSet owner

Templates

Templates make a configured starting point reusable. Agent, Computer, and Browser Templates are separate resources because they capture different things.

Use snapshot operations to publish the supported capture. A request or version ID identifies immutable input; equal replay returns its original result, while changed input conflicts. A draft edit and a published version have different lifetimes.

Agent snapshotAgent versionComputer snapshotBrowser snapshot contract

Files & namespaces

The Organization filesystem holds working files, Agent programs, shared data, and namespace directories. A Session's namespace determines its saved working context. Sharing a file or directory requires its own permission grant.

Use the filesystem command operation for authorized offline Bash in the Agent’s persistent sandbox, with the caller’s file view at /workspace. The native mount operation exposes the authorized tree through its WebSocket transport. It does not create a separate HTTP operation for each file action.

Filesystem permissions target nodes and can be listed, created, updated, and removed. Namespace permissions control namespace access. Agent permissions, namespace permissions, and file grants each apply at their own boundary.

Use Computer SSH and commands for files inside a Computer. Those files and the Organization filesystem have separate owners and access paths.

Filesystem commandNative mountFile permissionNamespace permission

Vault

Vault stores encrypted credentials and private input values. Applications write values and receive metadata and references. Read operations return metadata without returning the plaintext value.

Each secret has one immutable scope owner: an Organization, Organization User membership, Agent, or Agent Template. Its consumer constraints name the permitted use and destination. The current contract supports provider connections, HTTP substitution, private desktop and browser input, and enrollment. MCP OAuth grants are saved by the authorization flow.

Use references

Provider connections use the secret's exact ID and version. Private input uses a completion-vault:UUID reference. HTTP substitution uses withcompletion.com/vault/ENCODED_NAME in an authorized request; this is a placeholder, not a public URL to fetch a secret.

The authorized consumer resolves a reference privately for its permitted destination. A matching name or reference does not grant permission. HTTP target restrictions and current caller authority still apply.

Rotate or revoke

Supply a new write-only value to rotate a secret. Existing bound versions retain their declared lifetime. Update http_targets to replace the HTTP destination policy; an empty list disables substitution. Scope and consumer destination stay immutable. Revocation removes future authorized use under the current contract.

Create secretRead metadataRotate valueRevoke secret

Network Rules

Network Rules restrict Computer connections when the Organization's Computer VPN is enabled. Computer command proxies and HTTP MCP routed through a Computer enforce the selected policy. Generic Agent runtime HTTP, remote MCP without a Computer route, Workflows, and builds are outside this boundary.

Choose block_matches to deny matching traffic or block_except to deny traffic that does not match. Values within a selector combine with OR; different selectors combine with AND. An applicable denial wins, and an action approval cannot override it.

Connection rules accept supported IP, CIDR, hostname, protocol, and port selectors. A leading *. matches subdomains but not the apex. HTTP rules match scheme, host, effective port, method, and canonical path. Query strings and fragments are not path selectors.

HTTPS rules that inspect methods or paths require the command HTTP proxy. Uninspected encrypted traffic cannot satisfy that policy. Use the full rule schemas for exact matching, validation, and supported scope fields.

Create ruleReplace supplied fieldsRule matching schema

Action reviews

An action review lets a permitted person decide whether a specific Agent action can proceed. The review binds to that action's input. It does not grant broad permission for future actions.

Request a review for the Session and native task, list or read its state, then record approve or deny. A pending review can be cancelled. Execution checks consumption internally; customers record the decision.

A review record is decision evidence. Read the Agent's subsequent output for the tool result. Private desktop actions also have dedicated input and cancellation operations for actions the Agent has already created.

Review actionList reviewsRecord decisionCancel review

Organizations & sharing

An Organization groups members, resources, service configuration, and access policy. A user can belong to multiple Organizations. Account operations describe the current user; Organization operations act within the selected Organization.

Membership role, resource ownership, explicit sharing, and API-key scope all affect authority. Resource ownership can be assigned to a current member or cleared. Removing an owning member clears ownership while retaining the resource.

Computer and Computer Template sharing supports member and Organization permissions. Agent and namespace grants use their own permission operations. Filesystem grants apply to their selected nodes.

Use list-row metadata such as can_use and can_manage, where returned, to inform controls. The server still validates current authority when an operation runs.

MembersResource ownerComputer sharingAgent grant

API conventions

Responses and errors

Ordinary SDK calls return an APIResponse with status_code, headers, and decoded data. Read the status before treating data as success. Streaming methods return their native stream or WebSocket; close what you open and choose a client timeout suitable for the work.

Errors use {"error": "message"}, optionally with code and details. Each operation in the reference declares its success and error responses. Missing configured services can return 503.

Updates

PUT assigns supplied writable fields and preserves omitted fields. A supplied object or array replaces that field. false, [], and "" are values where allowed. Use null only on nullable fields; for example, voice: null clears voice settings.

The Python SDK uses UNSET for omission. Explicit None is sent as JSON null. Closed JSON bodies use keyword arguments at the top level; open JSON uses data, and binary input uses content.

Lists and search

Growing lists use a positive limit and opaque cursor. Completion pages return items, next_cursor, and has_more. The usual default limit is 50; the operation declares its bounds. Pass the returned cursor with the same caller, Organization, route, and filters.

Use q for free-text search only where declared. Each operation describes searched fields, case handling, and empty-value behavior. Repeat array filter parameters as declared. Native search and page shapes keep their own rules.

IDs and immutable requests

Use the declared UUID or request identifier for creation and lifecycle actions. Matching immutable replay returns its saved result; changed reuse returns a conflict. A receipt describes the admitted operation and does not imply that downstream execution has completed.

Browse the complete API reference

In development

Completion's broader design includes voice connections on existing Sessions, published Workflows, schedules, Events, and durable Goals. These capabilities are not exposed by the current public OpenAPI contract shown in this reference. Integration details and availability will be documented as their public surfaces are enabled.

Voice

Voice connects live audio to an existing Session while the core Agent owns tool execution. The design separates media, context updates, admitted work, and playback. Applications retain their phone calls and expose call actions such as hangup through their own MCP tools.

Workflows, Events, and Goals

Workflows describe published, repeatable work with execution-owned waits and step results. Events carry immutable facts used by authorized subscriptions. Goals describe ongoing Agent objectives. Delivery, retries, cancellation, and recovery need their own real-service verification before availability claims.

For early access or a specific integration, contact the team.