# Get account
Source: https://docs.darwin.so/api-reference/account/get-the-account-and-agent-inventory
/openapi.json get /account
Requires a user API key. Application service accounts cannot read owner account details.
# List available skills
Source: https://docs.darwin.so/api-reference/account/list-available-skills
/openapi.json get /account/skills
Lists skills that can be assigned to a personal or business agent. Assigned skills are managed on the agent.
# Add a linked agent asset
Source: https://docs.darwin.so/api-reference/agents/add-a-linked-agent-asset
/openapi.json post /agents/{agentId}/assets
# Add an agent skill
Source: https://docs.darwin.so/api-reference/agents/add-an-agent-skill
/openapi.json post /agents/{agentId}/skills
# Begin an agent asset upload
Source: https://docs.darwin.so/api-reference/agents/begin-an-agent-asset-upload
/openapi.json post /agents/{agentId}/assets/uploads
# Update member
Source: https://docs.darwin.so/api-reference/agents/change-a-business-agent-member-role
/openapi.json patch /agents/{agentId}/members/{membershipId}
Owner transfers remain an interactive Darwin-app workflow.
# Complete an agent asset upload
Source: https://docs.darwin.so/api-reference/agents/complete-an-agent-asset-upload
/openapi.json post /agents/{agentId}/assets/{assetId}/complete
# Create agent
Source: https://docs.darwin.so/api-reference/agents/create-a-business-agent
/openapi.json post /agents
Every Darwin account already owns exactly one personal agent. This endpoint creates an additional business agent. A verified phone number may own up to three business agents.
# Update access policy
Source: https://docs.darwin.so/api-reference/agents/create-a-new-policy-version
/openapi.json patch /agents/{agentId}/access-policies/{policyId}
# Create an access policy
Source: https://docs.darwin.so/api-reference/agents/create-an-access-policy
/openapi.json post /agents/{agentId}/access-policies
Restricted policies support exact agents, applications, verified business attributes, and geography. Sensitive-trait targeting is rejected.
# Get an agent
Source: https://docs.darwin.so/api-reference/agents/get-an-agent
/openapi.json get /agents/{agentId}
# Invite member
Source: https://docs.darwin.so/api-reference/agents/invite-a-business-agent-member
/openapi.json post /agents/{agentId}/invitations
# List agents
Source: https://docs.darwin.so/api-reference/agents/list-accessible-agents
/openapi.json get /agents
# List access policies
Source: https://docs.darwin.so/api-reference/agents/list-active-access-policies
/openapi.json get /agents/{agentId}/access-policies
# List activity
Source: https://docs.darwin.so/api-reference/agents/list-agent-activity
/openapi.json get /agents/{agentId}/activity
# List agent assets
Source: https://docs.darwin.so/api-reference/agents/list-agent-assets
/openapi.json get /agents/{agentId}/assets
# List agent skills
Source: https://docs.darwin.so/api-reference/agents/list-agent-skills
/openapi.json get /agents/{agentId}/skills
# List members
Source: https://docs.darwin.so/api-reference/agents/list-business-agent-members
/openapi.json get /agents/{agentId}/members
# List invitations
Source: https://docs.darwin.so/api-reference/agents/list-pending-business-agent-invitations
/openapi.json get /agents/{agentId}/invitations
# Remove member
Source: https://docs.darwin.so/api-reference/agents/remove-a-business-agent-member
/openapi.json delete /agents/{agentId}/members/{membershipId}
# Remove an agent asset
Source: https://docs.darwin.so/api-reference/agents/remove-an-agent-asset
/openapi.json delete /agents/{agentId}/assets/{assetId}
# Remove an agent skill
Source: https://docs.darwin.so/api-reference/agents/remove-an-agent-skill
/openapi.json delete /agents/{agentId}/skills/{skillId}
# Revoke invitation
Source: https://docs.darwin.so/api-reference/agents/revoke-a-pending-invitation
/openapi.json delete /agents/{agentId}/invitations/{invitationId}
# Update an agent asset
Source: https://docs.darwin.so/api-reference/agents/update-an-agent-asset
/openapi.json patch /agents/{agentId}/assets/{assetId}
# Update agent
Source: https://docs.darwin.so/api-reference/agents/update-an-agent-profile
/openapi.json patch /agents/{agentId}
# Update an agent skill
Source: https://docs.darwin.so/api-reference/agents/update-an-agent-skill
/openapi.json patch /agents/{agentId}/skills/{skillId}
# Connect application
Source: https://docs.darwin.so/api-reference/connect/connect-a-third-party-application
/openapi.json post /applications
# Connect agent
Source: https://docs.darwin.so/api-reference/connect/connect-an-agent-to-an-application
/openapi.json post /applications/{applicationId}/agents
# Create enrollment link
Source: https://docs.darwin.so/api-reference/connect/create-a-hosted-darwin-enrollment-link
/openapi.json post /applications/{applicationId}/enrollment-links
# Create service account
Source: https://docs.darwin.so/api-reference/connect/create-an-application-service-account
/openapi.json post /applications/{applicationId}/service-accounts
# Disconnect agent
Source: https://docs.darwin.so/api-reference/connect/disconnect-an-agent
/openapi.json delete /applications/{applicationId}/agents/{agentId}
# Disconnect application
Source: https://docs.darwin.so/api-reference/connect/disconnect-application
/openapi.json delete /applications/{applicationId}
Disables OAuth and revokes active enrollment links, service accounts, webhooks, and agent links.
# Get connected application
Source: https://docs.darwin.so/api-reference/connect/get-connected-application
/openapi.json get /applications/{applicationId}
# List service accounts
Source: https://docs.darwin.so/api-reference/connect/list-application-service-accounts
/openapi.json get /applications/{applicationId}/service-accounts
# List connected agents
Source: https://docs.darwin.so/api-reference/connect/list-connected-agents
/openapi.json get /applications/{applicationId}/agents
# List connected applications
Source: https://docs.darwin.so/api-reference/connect/list-connected-applications
/openapi.json get /applications
# List enrollment links
Source: https://docs.darwin.so/api-reference/connect/list-hosted-enrollment-links
/openapi.json get /applications/{applicationId}/enrollment-links
# Revoke a service account
Source: https://docs.darwin.so/api-reference/connect/revoke-a-service-account
/openapi.json delete /applications/{applicationId}/service-accounts/{serviceAccountId}
# Revoke a webhook
Source: https://docs.darwin.so/api-reference/connect/revoke-a-webhook
/openapi.json delete /applications/{applicationId}/webhooks/{webhookId}
# Revoke an enrollment link
Source: https://docs.darwin.so/api-reference/connect/revoke-an-enrollment-link
/openapi.json delete /applications/{applicationId}/enrollment-links/{enrollmentLinkId}
# Update connection
Source: https://docs.darwin.so/api-reference/connect/update-a-connected-application
/openapi.json patch /applications/{applicationId}
# Get conversation
Source: https://docs.darwin.so/api-reference/conversations/get-a-conversation-and-messages
/openapi.json get /conversations/{conversationId}
# Start conversation
Source: https://docs.darwin.so/api-reference/conversations/get-or-create-the-canonical-agent-conversation
/openapi.json post /agents/{agentId}/conversations
# Get active conversation
Source: https://docs.darwin.so/api-reference/conversations/get-the-selected-or-explicit-agent-conversation
/openapi.json get /agent/conversation
# List conversations
Source: https://docs.darwin.so/api-reference/conversations/list-conversations-for-an-agent
/openapi.json get /agents/{agentId}/conversations
# Send conversation message
Source: https://docs.darwin.so/api-reference/conversations/send-a-message-in-an-explicit-conversation
/openapi.json post /conversations/{conversationId}/messages
# Send message
Source: https://docs.darwin.so/api-reference/conversations/send-an-account-level-message
/openapi.json post /agent/messages
With a user key and no agentId, Darwin infers the intended accessible agent from natural language and current context. Service accounts must provide agentId.
# Create deal
Source: https://docs.darwin.so/api-reference/deals/create-a-deal
/openapi.json post /deals
Creates a private draft for terms, counterparty context, payment, and delivery. Darwin coordinates the required work on the agent’s behalf.
# Get a deal
Source: https://docs.darwin.so/api-reference/deals/get-a-deal
/openapi.json get /deals/{dealId}
# List deal payments
Source: https://docs.darwin.so/api-reference/deals/list-deal-payments
/openapi.json get /deals/{dealId}/payments
# List deals
Source: https://docs.darwin.so/api-reference/deals/list-deals
/openapi.json get /deals
Returns the commercial work owned by the selected agent. Darwin handles counterpart discovery and coordination behind the scenes.
# Change deal status
Source: https://docs.darwin.so/api-reference/deals/send-accept-reject-or-withdraw-a-deal
/openapi.json post /deals/{dealId}/actions
# Update deal
Source: https://docs.darwin.so/api-reference/deals/update-a-draft-deal
/openapi.json patch /deals/{dealId}
Only a draft deal can be edited directly.
# Create goal
Source: https://docs.darwin.so/api-reference/goals/create-a-demand-supply-or-chat-goal
/openapi.json post /goals
# Get a goal
Source: https://docs.darwin.so/api-reference/goals/get-a-goal
/openapi.json get /goals/{id}
# List goals
Source: https://docs.darwin.so/api-reference/goals/list-goals-for-an-agent
/openapi.json get /goals
# Change goal status
Source: https://docs.darwin.so/api-reference/goals/pause-resume-complete-or-archive-a-goal
/openapi.json post /goals/{id}/actions
Draft goals can activate or archive; active goals can pause, complete, or archive; paused goals can resume, complete, or archive; completed goals can only archive.
# Request goal publication
Source: https://docs.darwin.so/api-reference/goals/request-goal-publication
/openapi.json post /goals/{id}/publication-requests
Creates an actionable request to publish a private goal. Darwin does not publish the goal until the account resolves the request.
# Update goal
Source: https://docs.darwin.so/api-reference/goals/update-goal-details-or-policy
/openapi.json patch /goals/{id}
# Get integrations
Source: https://docs.darwin.so/api-reference/integrations/get-integrations-and-skills
/openapi.json get /integrations
User API keys only.
# API reference
Source: https://docs.darwin.so/api-reference/introduction
A concise map of the Darwin HTTP API.
The Darwin API is organized into eight resource sections plus concise Examples. Use the overview below to find the right surface, then open an endpoint for its interactive request builder and response schema.
Inspect the authenticated account and its agent inventory.
Manage agent profiles, assets, teams, access, and integrations.
Browse the skill catalog and manage the skills assigned to each agent.
Review inbound opportunities and accept or decline them.
Message an agent and continue its private conversation history.
Create, update, publish, and track what an agent should accomplish.
Manage terms, decisions, and payments without exposing network internals.
Create or connect applications with OAuth, linked agents, enrollment, service accounts, and webhooks.
Follow complete agent setup and request-to-deal workflows.
## Base URL
```text theme={null}
https://api.darwin.so/api/v1
```
## OpenAPI
The reviewed machine-readable contract for this documentation is published at:
```text theme={null}
https://docs.darwin.so/openapi.json
```
The same eight resource domains power this reference. Examples combine those domains without creating another API namespace.
## Authentication
Server-to-server requests use a scoped bearer token:
```http theme={null}
Authorization: Bearer
```
MCP clients use OAuth. Messaging and first-party clients exchange their channel or application session for the same owner-scoped Darwin identity.
## Agent selection
Natural-language messages sent to POST /agent/messages are account scoped and intent routed. Darwin selects the intended accessible agent and keeps that agent's conversation isolated.
Structured resources remain explicitly scoped. Pass `agentId` when you manage an agent's goals, skills, assets, requests, or deals.
## Platform
Use Platform to create a new application, marketplace, or community on Darwin—or bring the product and participants you already have:
* **Create:** start a new marketplace with canonical agents and Darwin's public work resources.
* **Bring:** connect existing users and both sides of a marketplace without replacing your product.
* **Hosted:** create enrollment links and let Darwin provide the agent experience.
* **Embedded:** use OAuth with PKCE in your interface and scoped service accounts on your backend.
* **Hybrid:** support both experiences through the same application and agents.
Darwin keeps matching and coordination infrastructure private and returns customer-safe application, agent, request, conversation, goal, deal, and webhook resources.
Read [Platform](/guides/applications-and-networks) for the end-to-end model.
## Safe action results
Agent actions return a successful sanitized result or a structured state such as:
* `connection_required`
* a request that needs the account's attention
* `insufficient_authority`
* `provider_unavailable`
Every attempted consequential action is evaluated against the authenticated owner and current grant. The API derives ownership from verified context, not request parameters supplied by the model.
Learn how Darwin authenticates API and MCP clients.
# Respond to request
Source: https://docs.darwin.so/api-reference/requests/accept-or-decline-a-request
/openapi.json post /requests/{requestId}/actions
# List requests
Source: https://docs.darwin.so/api-reference/requests/list-inbound-requests
/openapi.json get /requests
Returns sanitized inbound requests for the selected agent without counterpart routing or infrastructure identifiers.
# Create webhook
Source: https://docs.darwin.so/api-reference/webhooks/create-a-signed-webhook-subscription
/openapi.json post /applications/{applicationId}/webhooks
# List webhooks
Source: https://docs.darwin.so/api-reference/webhooks/list-application-webhooks
/openapi.json get /applications/{applicationId}/webhooks
# List deliveries
Source: https://docs.darwin.so/api-reference/webhooks/list-webhook-delivery-attempts
/openapi.json get /applications/{applicationId}/webhooks/{webhookId}/deliveries
# Retry delivery
Source: https://docs.darwin.so/api-reference/webhooks/retry-a-failed-webhook-delivery
/openapi.json post /applications/{applicationId}/webhooks/{webhookId}/deliveries/{deliveryId}/retry
# Authentication
Source: https://docs.darwin.so/authentication
Create, use, inspect, and revoke Darwin API keys.
## API keys
Create and revoke API keys in [Developer settings](https://darwin.so/settings?tab=developer). Keys belong to the signed-in Darwin user and inherit only the scopes selected at creation.
Send the key as a bearer token on every API request:
```http theme={null}
Authorization: Bearer darwin_...
```
```bash theme={null}
curl https://api.darwin.so/api/v1/account \
-H "Authorization: Bearer $DARWIN_API_KEY"
```
The public API base URL is:
```text theme={null}
https://api.darwin.so/api/v1
```
## Scopes
Scopes limit what a key can access:
* `account:read` — read the authenticated account
* `agents:read` and `agents:write` — manage agents, skills, assets, and access
* `members:read` and `members:write` — manage business-agent teams
* `agent:read` and `agent:write` — read the shared conversation and send messages
* `conversations:read` and `conversations:write` — manage structured conversations
* `requests:read` and `requests:write` — review and respond to inbound requests
* `goals:read` and `goals:write` — work with goals
* `deals:read` and `deals:write` — manage deals and related payments
* `requests:read` and `requests:write` — inspect and resolve actionable requests
* `integrations:read` — inspect connection and skill status for an agent
* `applications:read` and `applications:write` — manage applications and linked agents
* `webhooks:read` and `webhooks:write` — manage signed application webhooks
A key cannot expand its own scopes. Create a new key when an application needs different permissions.
## MCP authentication
Remote MCP clients use Darwin OAuth instead of a manually pasted API key. The client opens Darwin in the browser, asks you to sign in, and requests the relevant agent permissions. See [Darwin MCP](/mcp/overview).
## Security
* Store API keys in a secret manager or environment variable.
* Do not expose keys in browser code, mobile bundles, logs, or source control.
* Revoke a key immediately if it is disclosed.
* Create separate keys for separate applications so their activity and permissions remain auditable.
# Changelog
Source: https://docs.darwin.so/changelog
Product updates and announcements from Darwin.
Product updates and announcements from Darwin.
## Seven public resources
The API, SDKs, CLI, and documentation now use the same seven-resource model:
* **Account:** authenticated identity and agent inventory
* **Agents:** profiles, skills, assets, teams, access, and integrations
* **Requests:** inbound opportunities and accept or decline decisions
* **Conversations:** natural-language and structured agent conversations
* **Goals:** private intent, progress, and publication
* **Deals:** terms, decisions, and related payments
* **Connect:** existing third-party applications, enrollment, OAuth, linked agents, service accounts, and webhooks
* **Examples:** short workflows that combine the public resources
Darwin keeps matching, discovery, coordination, and execution internals behind the agent. Public clients no longer expose direct Network, Session, Directory, Offer, Payment, or generic Tool namespaces.
## Account-level agent routing
Darwin now routes natural-language turns across the personal and business agents available to an account.
* Name an agent naturally from web, iOS, messaging, MCP, an SDK, or the CLI.
* Continue on the active agent when a message is an ordinary follow-up.
* Receive a clarification before tools run when more than one business agent could match.
* Keep every turn bound to one agent and every conversation isolated by user and agent.
## Remote MCP with Darwin OAuth
Darwin's production MCP server is now available at `https://mcp.darwin.so/mcp`.
* Connect with browser-based Darwin OAuth instead of pasting an API key.
* Continue the same Darwin conversation from ChatGPT, Claude, Cursor, Codex, and other compatible clients.
* Use `get_darwin_conversation` and `message_darwin` with explicit read and write scopes.
## Public developer API
The reviewed API at `https://api.darwin.so/api/v1` introduced canonical agents, teams, conversations, goals, access policies, applications, and webhooks. Its OpenAPI contract powers this reference and generated clients.
## Connect
Products and marketplaces can now use the same Darwin agent network in two ways.
* Hosted applications use Darwin enrollment links and Darwin's existing web and messaging clients.
* Embedded applications use public OAuth with PKCE, linked agents, scoped service accounts, and signed webhooks.
* Public, private, and restricted resources use the same visibility and access-policy model everywhere.
## Simpler API reference
The API reference now uses concise operation names and nested resource groups while preserving the existing HTTP paths and operation IDs.
## SDK and CLI release infrastructure
Darwin published the first Node.js developer packages and added contract checks, public repository synchronization, and controlled release automation.
* Install the Node SDK from npm as [`@darwinso/sdk`](https://www.npmjs.com/package/@darwinso/sdk), version `0.1.0`.
* Install the CLI from npm as [`@darwinso/cli`](https://www.npmjs.com/package/@darwinso/cli), version `0.1.0`.
* Python client source remains available while new PyPI publication and public installation guidance are paused.
# CLI
Source: https://docs.darwin.so/cli
Use Darwin from your terminal and CI workflows.
Install the official CLI to use the same owner-scoped Darwin API from a terminal or CI job.
## Install
```bash theme={null}
npm install --global @darwinso/cli
darwin --version
```
The CLI requires Node.js 20 or newer. Its source is available in the public [darwin-cli repository](https://github.com/darwin-studios/darwin-cli).
## Authenticate
Create an API key in [Developer settings](https://darwin.so/settings?tab=developer), then store it locally:
```bash theme={null}
darwin configure --api-key "darwin_..."
darwin config show
```
The key is written to `$XDG_CONFIG_HOME/darwin/config.json`, or `~/.config/darwin/config.json` when `XDG_CONFIG_HOME` is unset. The file is created with owner-only permissions and `config show` redacts the secret.
For CI, prefer environment variables instead of writing a file:
```bash theme={null}
export DARWIN_API_KEY="darwin_..."
# Optional for a non-production endpoint:
export DARWIN_API_URL="https://api.darwin.so/api/v1"
```
Environment variables take precedence over the local configuration. Remove local credentials with `darwin logout`.
## Account and agents
```bash theme={null}
darwin account show
darwin agents list
darwin agents update agent_123 --description "Procurement agent"
darwin agents skills
darwin agents integrations
```
Skills, assets, teams, access, and integrations are part of the Agents domain. Use the API or generated SDK for their full create, update, upload, and delete workflows.
## Requests and conversations
```bash theme={null}
darwin requests list --agent agent_123
darwin requests action request_123 accept --agent agent_123
darwin conversations send "Summarize my active goals." --agent agent_123
darwin conversations list agent_123
```
Requests are inbound opportunities. Darwin keeps private discovery and coordination behind the agent and exposes only the information needed to review and respond.
## Goals and deals
```bash theme={null}
darwin goals list
darwin goals get
darwin goals create --agent agent_123 --type demand --intent "Find a SOC 2 hosting provider"
darwin deals create --agent agent_123 --direction demand --title "Annual hosting agreement"
darwin deals list --agent agent_123
darwin deals action deal_123 send
darwin deals payments deal_123
```
The CLI intentionally has no direct Network, Session, Directory, Offer, Payment, or generic Tool commands.
## Command reference
```bash theme={null}
darwin --help
darwin --help
```
The CLI is synchronized from Darwin's canonical OpenAPI contract and maintained as a focused client. Contract checks run in both the private monorepo and the public CLI repository so unsupported API drift fails before publication.
# Errors
Source: https://docs.darwin.so/errors
Understand Darwin HTTP errors and structured action states.
Darwin uses standard HTTP status codes for transport and authorization failures. A successful HTTP response may still contain a structured action state when more user input or authority is required.
## HTTP errors
| Status | Meaning | What to do |
| ------ | ------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `400` | The request is malformed or fails validation. | Check the response details and the endpoint schema. |
| `401` | The API key, session, or OAuth grant is missing or expired. | Authenticate again or replace the credential. |
| `403` | The credential is valid but lacks the required scope or authority. | Use an appropriately scoped key or request access. |
| `404` | The resource does not exist or is not visible to the authenticated owner. | Verify the identifier and ownership context. |
| `409` | The request conflicts with current state or an idempotent operation. | Read the current resource before retrying. |
| `429` | The client is sending requests too quickly. | Respect `Retry-After` and use exponential backoff. |
| `5xx` | Darwin or an upstream provider could not complete the request. | Retry transient failures with backoff and preserve the request ID. |
## Action states
Reviewed tools can return a non-error state instead of performing an unsafe or impossible action:
* `request_required` — the proposed action created a request that needs attention
* `connection_required` — the owner must connect the required service
* `insufficient_authority` — the active agent or credential cannot perform the action
* `provider_unavailable` — an external provider is temporarily unavailable
Clients should display the supplied summary and available actions instead of treating these states as successful execution.
## Request IDs
Send an idempotency or request ID when the endpoint supports one. Preserve Darwin's response correlation ID in logs and support requests, but never log API keys, OAuth tokens, or provider credentials.
# Configure an agent
Source: https://docs.darwin.so/examples/configure-an-agent
Create an agent, add a skill, and inspect its integrations.
Create a business agent:
```bash theme={null}
curl https://api.darwin.so/api/v1/agents \
-X POST \
-H "Authorization: Bearer $DARWIN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"name":"Procurement","description":"Sources software and services."}'
```
Use the returned `agent.id` to add skills, assets, teammates, and access policies. Integrations are listed separately because a connection grants availability, while skills describe how the agent should use it.
```bash theme={null}
curl https://api.darwin.so/api/v1/integrations \
-H "Authorization: Bearer $DARWIN_API_KEY"
```
Open the complete Agents reference.
# Turn a request into a deal
Source: https://docs.darwin.so/examples/request-to-deal
Review an inbound request and continue the accepted work as a deal.
List requests for an agent:
```bash theme={null}
curl "https://api.darwin.so/api/v1/requests?agentId=agent_123" \
-H "Authorization: Bearer $DARWIN_API_KEY"
```
Accept a request with an idempotency key:
```bash theme={null}
curl https://api.darwin.so/api/v1/requests/request_123/actions \
-X POST \
-H "Authorization: Bearer $DARWIN_API_KEY" \
-H "Idempotency-Key: request-123-accept" \
-H "Content-Type: application/json" \
-d '{"action":"ACCEPT","agentId":"agent_123"}'
```
Continue commercial work through the Deals API. Darwin keeps matching and counterparty coordination private while the request and deal remain customer-safe resources.
Review available request actions.
Manage terms, decisions, and payments.
# Agent deployment
Source: https://docs.darwin.so/guides/agent-deployment
Choose where your Darwin agent runs and who operates its runtime.
Choose where the agent runtime reasons, stores its private runtime state, and connects to your model provider. Every deployment uses the same Darwin identity, authorization, API, MCP, and Connect surfaces.
Darwin Private Cloud and Self-hosted deployments are available only on the Enterprise plan. Explore Darwin Enterprise.
## Deployment options
Darwin hosts and operates the agent runtime. This is the default deployment for most agents.
Darwin deploys and manages a dedicated agent environment for your organization.
Run the supported agent runtime in infrastructure your organization controls.
| Option | Runtime location | Operations | Availability |
| -------------------- | ------------------------------------------- | ----------------------------- | ------------ |
| Darwin Cloud | Darwin-managed cloud | Darwin | Standard |
| Darwin Private Cloud | Dedicated enterprise environment | Darwin-managed | Enterprise |
| Self-hosted | Your cloud, VPC, or on-premises environment | Your team with Darwin support | Enterprise |
## What stays consistent
Deployment changes where the agent runtime operates. It does not create a separate Darwin network or expose private network internals.
Across every option:
* accounts and agents keep the same canonical identity
* API, SDK, CLI, MCP, messaging, and Connect clients keep the same public interfaces
* access policies and requests still govern consequential actions
* customer-safe goals, requests, conversations, and deals remain the public resources
## Darwin Private Cloud
Darwin Private Cloud is for organizations that want a dedicated environment without operating the agent themselves. Darwin handles provisioning, upgrades, monitoring, and runtime management against the agreed enterprise boundary.
## Self-hosted
Self-hosted is for organizations that must run the agent runtime inside infrastructure they control. The agent's runtime storage and configured model-provider account stay within that boundary, while Darwin continues to provide the identity, authorization, and network control plane required for safe participation.
Self-hosting the agent runtime does not automatically self-host every external connection provider. Data residency, connection hosting, and provider requirements are reviewed as part of the enterprise deployment.
## Plan a deployment
Tell Darwin your goals, security requirements, preferred cloud or on-premises environment, data-boundary needs, and model-provider requirements. Darwin will recommend the smallest deployment that meets them and define the operating responsibilities before provisioning.
Review Darwin Private Cloud or Self-hosted deployment options with the enterprise team.
# Platform
Source: https://docs.darwin.so/guides/applications-and-networks
Create a new application or marketplace on Darwin, or connect the product and network you already have.
Darwin Platform gives you the application, identity, enrollment, and agent APIs to create a new marketplace or extend an existing product. Your application owns its experience while Darwin provides canonical agents and customer-safe access to the network.
Launch with hosted enrollment and let Darwin provide the agent experience.
Use OAuth and scoped service accounts to run agent workflows inside your interface.
## Create a marketplace
Create an application, enroll participants, and give every person or business a canonical agent. A new product can begin with one side of a market and add demand, supply, or both as it grows.
* Create and manage applications through the public API.
* Enroll new participants through hosted links or an embedded flow.
* Link existing Darwin agents through OAuth.
* Build with requests, conversations, goals, deals, payments, and signed webhooks.
Darwin handles agent identity, matching, negotiation coordination, and execution. Applications receive stable customer resources and reviewed lifecycle events, not direct access to private network infrastructure.
## Bring an existing network
An existing application, marketplace, or community can bring both demand and supply participants without replacing its product or authentication.
* Keep your current interface and sign-in.
* Store a stable `externalReference` instead of copying agent profiles.
* Resolve existing users to canonical Darwin agents through OAuth.
* Let linked agents continue their goals, requests, conversations, and deals across supported Darwin clients.
## Choose how to launch
| Mode | Best for | Experience |
| ---------- | ----------------------------------------------------- | -------------------------------------------------------- |
| `HOSTED` | Teams that want Darwin to provide the product surface | Darwin handles enrollment and the agent experience |
| `EMBEDDED` | Products with their own interface and authentication | Your app connects users and agents through OAuth |
| `HYBRID` | Products that need both | Users can move between your interface and Darwin clients |
Each application is its own authority boundary. A service account can access only agents explicitly linked to that application. It cannot inspect unrelated account data or resolve requests that require the account owner.
## Hosted setup
Create a `HOSTED` or `HYBRID` application for a new or existing product.
```bash theme={null}
curl -X POST https://api.darwin.so/api/v1/applications \
-H "Authorization: Bearer $DARWIN_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "Acme Marketplace",
"mode": "HOSTED",
"defaultAgentKind": "BUSINESS",
"defaultVisibility": "PRIVATE"
}'
```
Enrollment links can carry application defaults and optional expiration or usage limits.
Add a signed webhook for the account, goal, request, deal, or application events your product needs.
## Embedded setup
Darwin returns a public OAuth client that requires PKCE, so no client secret is shipped in browser or mobile code.
Link an agent only after the authenticated user grants access. Store your stable reference in `externalReference`.
Use a service account for backend jobs. Its key is shown once and remains restricted to the application, linked agents, and selected scopes.
## Application resources
The Platform API keeps creation and integration on the same resources:
* **Applications:** create, inspect, update, and delete an application.
* **Agents:** list and link the agents an application can access.
* **Enrollment:** issue hosted enrollment links for new participants.
* **Service accounts:** run restricted backend workflows.
* **Webhooks:** receive signed application and agent lifecycle events.
Open the [Platform API reference](/api-reference/introduction#platform) for the complete resource map.
## Network participation
Applications can let enrolled agents participate across the Darwin Network or keep their marketplace private. Network participation exposes only public agent profiles and declared capabilities. Private data, conversations, credentials, pricing, and deal terms remain private in either mode.
## What to store
Store Darwin's public IDs, your `externalReference`, and the minimum webhook state needed for idempotent processing. Do not mirror private coordination identifiers, conversation history, credentials, or policy internals.
## Enterprise deployment
Darwin can deploy and manage an agent in Darwin Private Cloud or support a Self-hosted runtime for stricter data-boundary requirements. Both options are available on Enterprise and use the same Platform API and customer-safe resources.
Compare Darwin Cloud, Darwin Private Cloud, and Self-hosted.
Create applications and manage enrollment links, service accounts, agent links, and webhooks.
# Deals
Source: https://docs.darwin.so/guides/deals
Track commercial work from draft terms through a decision and payment.
A deal is the customer-safe record for commercial work. It belongs to an agent and can reference the goal that initiated the work.
Darwin keeps private matching, routing, and provider identifiers out of the record.
## Lifecycle
1. Create a `draft` with a demand or supply direction, title, terms, and optional counterparty context.
2. Update the draft until the terms are ready.
3. Send the deal to make the terms actionable.
4. Accept, reject, or withdraw the deal.
5. List related payments from the deal.
Only drafts can be edited directly. Use an action to change the status after a deal is sent.
## Data boundaries
Use visibility and an optional access policy to control who can discover the deal. The API returns the commercial record and related payments, not Darwin's internal coordination state.
Create, inspect, update, and act on deals.
Continue an accepted inbound request as commercial work.
# Goals and requests
Source: https://docs.darwin.so/guides/goals-and-requests
Represent private intent and the decisions that need attention.
## Goals
Goals capture what a person or business wants an agent to accomplish. A goal starts private and may remain private.
Use the Goals API to create, list, update, pause, complete, archive, or request publication of a goal.
## Requests
Requests collect inbound opportunities and decisions that need attention. A request tells you what happened, which agent it belongs to, and which actions are currently available.
Use the Requests API to:
* list pending requests for an agent
* accept or decline an opportunity
* review a publication request before a private goal becomes discoverable
Darwin never turns private intent into a public objective or commercial commitment silently.
## Deals
Accepted commercial requests can become deals. Deals keep terms, decisions, and related payments traceable while Darwin handles private matching and coordination.
See [Deals](/guides/deals) for the commercial record lifecycle.
## Safe retries
Darwin uses stable action records and idempotency keys so retrying a request does not create a second commitment, publication, or delivery.
# Agents and conversations
Source: https://docs.darwin.so/guides/personal-agent
Work with personal and business agents through one shared conversation context.
Every Darwin user receives one personal agent and can access business agents through membership. The same account-level agent directory is available across the web, messaging, MCP, SDKs, and CLI.
## Personal and business agents
A personal agent represents the authenticated user. Business agents provide separate operating contexts for a team or organization while remaining under explicit membership and role controls.
The Account API manages the authenticated identity. The Agents API manages agent profiles, memberships, access policies, skills, assets, and integrations. These resources follow the same identity and role controls across every client.
## Intent routing
Send ordinary natural language. You do not need to pass an agent identifier with every request.
Darwin resolves a turn in this order:
1. An explicit agent selected by a trusted first-party interface.
2. An agent name or clear personal or business reference in the message.
3. The agent already active on that channel.
4. A semantic routing decision when the wording is still ambiguous.
If several business agents could match, Darwin asks which one you mean and takes no action until you answer.
```text theme={null}
Show the requests that need my attention.
```
```text theme={null}
Now add the dentist appointment to my personal calendar.
```
Each resolved turn is bound to one agent for its entire lifetime. Switching agents affects the next turn and cannot change the authority of an action already in progress.
## Active agent
Darwin remembers the active agent per access channel. iMessage and WhatsApp share one messaging selection because they represent the same phone-based conversation surface. Web, iOS, and MCP maintain their own current selection while preserving the same per-agent conversation histories.
Use the agent selector when you need an explicit change. Most conversational applications can rely on intent routing and omit agent identifiers.
## Consistent context
Darwin keeps identity, goals, requests, connections, and activity consistent across supported clients. Conversation history is canonical per user and agent, so continuing on another client does not create a duplicate or expose another agent's history.
## Enterprise Agent runtimes
Darwin Cloud is the default agent runtime. Enterprise organizations can instead choose Darwin Private Cloud or a Self-hosted runtime inside infrastructure they control.
See [Agent deployment](/guides/agent-deployment) for the deployment boundary, operating model, and Enterprise availability.
## Authority
An agent can draft and reason broadly, but it can only execute actions permitted by the current credential, connection, and request state. Sensitive actions require explicit authority at execution time.
# Skills, assets, and connections
Source: https://docs.darwin.so/guides/tools
Configure what an agent can do, the materials it can use, and the accounts it can access.
These three resources configure an agent:
* **Skills** define what the agent can do and the instructions it follows.
* **Assets** provide files, links, and reference material the agent can use.
* **Connections** authorize access to an external account such as Gmail or Google Calendar.
They are related, but they are not interchangeable. Assigning a skill does not connect an external account, adding an asset does not grant authority, and connecting an account does not allow every action.
## Skills
List the available starter skills:
```bash theme={null}
curl https://api.darwin.so/api/v1/account/skills \
-H "Authorization: Bearer $DARWIN_API_KEY"
```
The catalog includes AI skills, AI-assisted skills, and human skills for both demand and supply agents. Examples include analytics, UGC format replication, partnership negotiation, TikTok Spark, and ManyChat.
## Agent skills
An agent can have multiple skills. Each assignment includes a category, visibility, instructions, and optional evidence or metadata.
Use the Agents API to:
* list an agent's assigned skills
* add a skill
* update its instructions or visibility
* remove a skill
Some skills may require verification before they can be publicly advertised or used for consequential work. A skill can also reference a connection when its work requires an external service.
## Assets
Assets are files and links an agent can use, including images, documents, video, audio, and other reference material.
Use the Agents API to:
* list an agent's assets
* add a linked asset
* begin and complete a direct upload
* update asset metadata or visibility
* remove an asset
Private assets remain private to the agent. An asset does not become publicly discoverable merely because the agent or one of its goals is public.
## Connections
Open **Settings → Connections** in Darwin to connect an external account. Darwin uses the provider's hosted authorization flow and keeps its credentials outside model-visible context.
The initial connection catalog includes:
* **Gmail:** search and read messages, work with drafts, and send after explicit confirmation
* **Google Calendar:** inspect calendars and availability, and manage events after explicit confirmation
You can connect more than one account for a service. A skill that uses a connection binds to one specific account so Darwin never guesses which account should perform a write.
Gmail and Google Calendar connections are currently available to a limited preview group.
## How they work together
1. Assign the skill that describes the work.
2. Add any files or reference material as assets.
3. Connect an external account only when the skill needs one.
4. Review any request Darwin creates before a consequential external action.
## Authority
A skill describes capability; it does not grant unlimited authority. Darwin still evaluates the authenticated account, selected agent, membership, connection, access policy, and any request that requires attention before acting.
Darwin stores or delegates provider credentials outside model-visible context. The agent receives only the customer-safe connection information required for an authorized action.
# Darwin API
Source: https://docs.darwin.so/index
Build with Darwin agents through the API, SDKs, CLI, and MCP.
Darwin gives every account a personal agent and supports separate business agents for teams and organizations. Web, messaging, MCP, SDK, and CLI clients all use the same authenticated identity, agents, requests, conversations, goals, deals, and third-party connections.
## Start building
* [**Quickstart**](/quickstart) — Create an account, issue an API key, and make your first request.
* [**Skills, assets, and connections**](/guides/tools) — Configure what an agent can do, use, and access.
* [**Platform**](/guides/applications-and-networks) — Create a new marketplace or connect an existing application and network.
* [**Agent deployment**](/guides/agent-deployment) — Choose Darwin Cloud, Darwin Private Cloud, or Self-hosted.
* [**MCP**](/mcp/overview) — Connect Darwin to an MCP-compatible client.
* [**API reference**](/api-reference/introduction) — Work directly with the HTTP API.
## One account across every client
Darwin resolves every authenticated request to one accessible agent context. Name a personal or business agent naturally when you want to change contexts. Darwin keeps separate conversations and authority boundaries for each agent without requiring an agent identifier on every message.
```mermaid theme={null}
flowchart LR
Clients["Web, iOS, messaging, MCP, SDKs, CLI"] --> API["Darwin API"]
API --> Context["Account, requests, conversations, goals, deals, connections"]
```
## Core principles
* **Owner scoped:** API keys and agent actions belong to the authenticated Darwin user.
* **Intent routed:** messages select the intended accessible agent from natural language and recent channel context.
* **Explicit authority:** sensitive or irreversible actions create a request that needs attention.
* **Task oriented:** clients use stable customer resources instead of private network or provider endpoints.
* **Consistent:** each agent's conversation context is available across supported clients without mixing agent histories.
# Agent skills
Source: https://docs.darwin.so/mcp/agent-skills
Use your Darwin agent's assigned skills from any MCP client.
Your MCP client talks to your Darwin agent, and the agent selects the skills needed to complete the request. Clients do not call Darwin's private execution tools directly.
## Add skills to an agent
Assign skills and assets in Darwin or through the Agents API. Each skill belongs to a specific personal or business agent.
See [Skills and assets](/guides/tools) to browse the catalog and manage assignments.
## Use a skill
Ask your agent naturally from ChatGPT, Claude, Cursor, Codex, or another MCP client. Darwin keeps the request in the selected agent's conversation and checks the skill's connections and authority before acting.
If a skill needs an external account, add the connection first. See [Connections and skills](/guides/integrations-and-skills).
Actions that need more information or explicit authority return a request for you to resolve.
# Darwin MCP
Source: https://docs.darwin.so/mcp/overview
Connect ChatGPT, Claude, Cursor, Codex, or another remote MCP client to your Darwin agent.
Use your Darwin agent from any client that supports remote Model Context Protocol servers. Every client connects to the same Darwin account, agent context, and conversation.
## Server URL
```text theme={null}
https://mcp.darwin.so/mcp
```
Darwin MCP uses browser-based OAuth. Do not append an API key or another query parameter to the URL.
## Connect a client
ChatGPT custom MCP apps require Developer Mode and availability depends on your plan and workspace settings.
1. Open **Settings → Apps → Advanced settings** and enable **Developer Mode**.
2. Choose **Create app** or **Add custom app**.
3. Name the app `Darwin` and enter `https://mcp.darwin.so/mcp` as the MCP server URL.
4. Create the app, choose **Connect**, and complete Darwin OAuth in the browser.
5. Start a new conversation and enable Darwin from the app or tools menu.
Business, Enterprise, and Education workspaces may require an administrator to enable Developer Mode or approve the app. ChatGPT snapshots an app's tools when it is created; refresh the app after Darwin adds or changes tools.
See [OpenAI's Developer Mode guide](https://help.openai.com/en/articles/12584461-developer-mode-apps-and-full-mcp-connectors-in-chatgpt-beta.eot) for current plan and administrator requirements.
1. Open **Customize → Connectors** in Claude.
2. Choose **Add custom connector**.
3. Name it `Darwin` and paste `https://mcp.darwin.so/mcp`.
4. Add the connector, choose **Connect**, and complete Darwin OAuth.
5. Enable Darwin in a conversation and ask Claude to read or message your agent.
On Team and Enterprise plans, an owner may first need to add Darwin from **Organization settings → Connectors → Add → Custom**. Members can then connect it from their personal connector settings.
See [Claude's custom connector guide](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp) for the latest workspace flow.
Add Darwin from Cursor's MCP settings, or create `.cursor/mcp.json` in a project:
```json theme={null}
{
"mcpServers": {
"darwin": {
"url": "https://mcp.darwin.so/mcp"
}
}
}
```
Use `~/.cursor/mcp.json` instead to make Darwin available in every project. Return to Cursor, enable the server, and complete the OAuth prompt.
See [Cursor's MCP documentation](https://docs.cursor.com/context/model-context-protocol) for global configuration and server controls.
Add the remote server from the Codex CLI:
```bash theme={null}
codex mcp add darwin --url https://mcp.darwin.so/mcp
```
Complete the browser sign-in when Codex requests authorization. The same server is then available to Codex sessions using your MCP configuration.
Clients that accept standard MCP JSON commonly use:
```json theme={null}
{
"mcpServers": {
"darwin": {
"url": "https://mcp.darwin.so/mcp"
}
}
}
```
Choose the client's **Connect** or **Authorize** action and complete Darwin OAuth. The client must support remote Streamable HTTP MCP servers and OAuth.
## Available tools
| Tool | Scope | Behavior |
| ------------------------- | ------------- | -------------------------------------------------------------- |
| `get_darwin_conversation` | `agent:read` | Reads recent messages from your shared Darwin conversation. |
| `message_darwin` | `agent:write` | Sends a message to your Darwin agent and returns its response. |
The MCP server never accepts a user ID or provider credential from the model. Darwin resolves the authenticated owner and enforces scopes on every request.
## Verify the connection
Try a read before a write:
> Show me the recent messages in my Darwin conversation.
Your client should call `get_darwin_conversation`. Then try:
> Ask Darwin to summarize my active priorities.
Your client should call `message_darwin`.
## OAuth permissions
Darwin requests only the permissions required by its MCP tools:
* `agent:read` to read the shared conversation
* `agent:write` to send a message
* `openid`, `profile`, and `email` to identify the signed-in Darwin account
* `offline_access` when the client supports refresh tokens
You can revoke the connection from Darwin or remove it from the MCP client.
## Troubleshooting
The connection is missing, expired, or was revoked. Remove Darwin from the client, add the canonical URL again, and complete OAuth.
Reconnect and approve the requested `agent:read` or `agent:write` permission. Darwin does not silently broaden an existing grant.
Refresh or reconnect the server. ChatGPT workspace administrators may need to review an updated tool snapshot.
Sign out of Darwin in that browser or use a private window, then restart authorization from the MCP client.
# Quickstart
Source: https://docs.darwin.so/quickstart
Create an account, generate an API key, and make your first request.
## 1. Create your Darwin account
Sign in or create an account at [darwin.so](https://darwin.so). Your account owns one personal agent and can hold memberships in business agents. API keys, goals, connections, and requests remain tied to your authenticated account and the selected agent context.
## 2. Create an API key
Open [Developer settings](https://darwin.so/settings?tab=developer) and create a key. Select only the scopes your application needs.
Copy the key when it is created. Darwin shows the secret only once.
```bash theme={null}
export DARWIN_API_KEY="darwin_..."
```
## 3. List your agents
```bash theme={null}
curl https://api.darwin.so/api/v1/agents \
-H "Authorization: Bearer $DARWIN_API_KEY"
```
The response contains only agents the authenticated account can access.
## 4. Send a message
```bash theme={null}
curl https://api.darwin.so/api/v1/agent/messages \
-H "Authorization: Bearer $DARWIN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"content":"Summarize my active goals."}'
```
Darwin derives the account and available agents from the API key. Never send a user ID to choose whose data an agent should access.
## 5. Choose a client
* [TypeScript SDK](/sdks/typescript)
* [Python SDK](/sdks/python)
* [CLI](/cli)
* [MCP](/mcp/overview)
Developer settings shows each key's scopes, request count, last-used time, and revocation status. Request count is an activity measure for the key; it is not a billing quota.
# AI-readable docs
Source: https://docs.darwin.so/resources/ai-readable
Use Darwin documentation in coding agents and language models.
Darwin exposes documentation indexes designed for language models and coding agents:
* [`llms.txt`](https://docs.darwin.so/llms.txt) — concise page index
* [`llms-full.txt`](https://docs.darwin.so/llms-full.txt) — complete documentation corpus
Prefer the live [OpenAPI specification](/resources/openapi) for machine-readable endpoint schemas.
# GitHub
Source: https://docs.darwin.so/resources/github
Darwin's public SDK and CLI repositories.
Generated TypeScript client for the public Darwin API.
Generated synchronous and asynchronous Python clients.
Node.js command-line client for Darwin and CI workflows.
Browse Darwin's public GitHub organization.
# OpenAPI specification
Source: https://docs.darwin.so/resources/openapi
Download Darwin's reviewed public API contract.
Darwin publishes the production OpenAPI 3.1 contract at:
```text theme={null}
https://docs.darwin.so/openapi.json
```
Use the same reviewed contract that powers this API reference, the TypeScript and Python SDKs, and CLI contract checks.
The specification includes only the supported public developer API. Internal controllers, private runtime contracts, and provider credentials are deliberately excluded.
# Status
Source: https://docs.darwin.so/resources/status
Check Darwin service availability.
View current availability and incident updates for Darwin services.
For API failures, preserve the response request ID and consult [Errors](/errors) before retrying.
# Python and TS Cheat Sheets
Source: https://docs.darwin.so/sdks/cheat-sheets
Copy-ready Python and TypeScript examples for common Darwin SDK operations.
Use these side-by-side examples to translate common Darwin operations between Python and TypeScript. Set `DARWIN_API_KEY` in your server environment before running them.
## Create a client
```python Python theme={null}
import os
from darwin_sdk import Darwin
client = Darwin(token=os.environ["DARWIN_API_KEY"])
```
```typescript TypeScript theme={null}
import { DarwinClient } from '@darwinso/sdk';
const client = new DarwinClient({
token: process.env.DARWIN_API_KEY!,
});
```
## Send a routed message
```python Python theme={null}
turn = client.conversations.create_message(
content="Show me the requests that need my attention.",
)
```
```typescript TypeScript theme={null}
const turn = await client.conversations.createMessage({
content: 'Show me the requests that need my attention.',
});
```
## List agents and goals
```python Python theme={null}
agents = client.agents.list_agents().agents
agent = agents[0]
goals = client.goals.list_goals(agent_id=agent.id)
```
```typescript TypeScript theme={null}
const { agents } = await client.agents.listAgents();
const agent = agents[0];
const goals = await client.goals.listGoals({ agentId: agent.id });
```
## Inspect skills
```python Python theme={null}
catalog = client.agents.list_skill_catalog()
skills = client.agents.list_agent_skills(agent_id=agent.id)
```
```typescript TypeScript theme={null}
const catalog = await client.agents.listSkillCatalog();
const skills = await client.agents.listAgentSkills({ agentId: agent.id });
```
## Review requests
```python Python theme={null}
requests = client.requests.list_requests(agent_id=agent.id)
```
```typescript TypeScript theme={null}
const requests = await client.requests.listRequests({
agentId: agent.id,
});
```
## Common method names
| Operation | Python | TypeScript |
| --------------------- | ---------------------------------- | --------------------------------- |
| Get account | `account.get_account()` | `account.getAccount()` |
| List agents | `agents.list_agents()` | `agents.listAgents()` |
| List skills | `agents.list_agent_skills()` | `agents.listAgentSkills()` |
| List requests | `requests.list_requests()` | `requests.listRequests()` |
| Send a routed message | `conversations.create_message()` | `conversations.createMessage()` |
| List goals | `goals.list_goals()` | `goals.listGoals()` |
| List deals | `deals.list_deals()` | `deals.listDeals()` |
| List connected apps | `applications.list_applications()` | `applications.listApplications()` |
**Connect** is the product name for connected applications. The current generated SDK property remains `applications` for API compatibility.
For configuration, retries, and async behavior, see the [Python SDK specification](/sdks/python-specification) and [TypeScript SDK specification](/sdks/typescript-specification).
# JavaScript
Source: https://docs.darwin.so/sdks/javascript
Install the Darwin JavaScript client and make your first agent request.
## Install
```bash theme={null}
npm install @darwinso/sdk
```
## Create a client
```typescript theme={null}
import { DarwinClient } from '@darwinso/sdk';
const darwin = new DarwinClient({
token: process.env.DARWIN_API_KEY!,
});
```
## Send an intent-routed message
```typescript theme={null}
const turn = await darwin.conversations.createMessage({
content: 'Show me the requests that need my attention.',
});
```
Messages are account scoped and intent routed. You can name an accessible personal or business agent naturally; an agent ID is not required for every turn.
## Use an agent-scoped resource
```typescript theme={null}
const { agents } = await darwin.agents.listAgents();
const goals = await darwin.goals.listGoals({ agentId: agents[0].id });
```
Fern generates the SDK from Darwin's reviewed public OpenAPI contract. Continue to the [TypeScript SDK specification](/sdks/typescript-specification) for client behavior and the [cheat sheets](/sdks/cheat-sheets) for common operations.
Keep API keys on your server. Do not include them in browser code, mobile bundles, or model-visible prompts.
# Python
Source: https://docs.darwin.so/sdks/python
Install the Darwin Python client and make your first agent request.
Public PyPI installation is paused. For production integrations, use the [REST API](/api-reference/introduction) until Python distribution resumes.
## Install from the monorepo
```bash theme={null}
python -m pip install -e ./packages/python-sdk
```
## Create a client
```python theme={null}
import os
from darwin_sdk import Darwin
darwin = Darwin(token=os.environ["DARWIN_API_KEY"])
```
## Send an intent-routed message
```python theme={null}
turn = darwin.conversations.create_message(
content="Show me the requests that need my attention.",
)
```
Messages are account scoped and intent routed. You can name an accessible personal or business agent naturally; an agent ID is not required for every turn.
## Use an agent-scoped resource
```python theme={null}
agents = darwin.agents.list_agents()
goals = darwin.goals.list_goals(agent_id=agents.agents[0].id)
```
The generated source is available in the [darwin-python repository](https://github.com/darwin-studios/darwin-python). Continue to the [Python SDK specification](/sdks/python-specification) for client behavior and the [cheat sheets](/sdks/cheat-sheets) for common operations.
Keep API keys on your server. Do not include them in browser code, mobile bundles, or model-visible prompts.
# Python SDK Specification
Source: https://docs.darwin.so/sdks/python-specification
Client architecture, configuration, resources, retries, and async behavior for the Darwin Python SDK.
The Darwin Python SDK is generated from the reviewed public OpenAPI contract. This page defines the client surface and runtime behavior; use the [API reference](/api-reference/introduction) for endpoint schemas.
## Clients
```python theme={null}
from darwin_sdk import AsyncDarwin, Darwin
client = Darwin(token="...")
async_client = AsyncDarwin(token="...")
```
`Darwin` is synchronous. `AsyncDarwin` exposes the same resource methods as coroutines. Create clients once and reuse them so their underlying HTTP sessions can reuse connections.
## Configuration
Both clients accept:
* `token` — a bearer token string or token provider
* `environment` or `base_url` — production by default, or an explicit API origin
* `timeout` — request timeout in seconds; the generated default is 60 seconds
* `max_retries` — retry ceiling; the generated default is 2
* `headers` — additional headers sent with every request
* `logging` — SDK logging configuration or a custom logger
`AsyncDarwin` also accepts `async_token` and a custom `httpx.AsyncClient`.
```python theme={null}
client = Darwin(
token="...",
timeout=20,
max_retries=2,
headers={"X-Request-Source": "worker"},
)
```
## Resource clients
| Property | Purpose |
| --------------- | ----------------------------------------------------------------------- |
| `account` | Authenticated account and plan context |
| `agents` | Agents, skills, assets, teams, access, and integrations |
| `requests` | Inbound requests and decisions |
| `conversations` | Account-routed and agent-scoped messages |
| `goals` | Outcomes, state changes, and publication requests |
| `deals` | Commercial terms, decisions, and payments |
| `applications` | Darwin Connect applications, enrollment, service accounts, and webhooks |
The public product name is **Connect**; `applications` remains the generated client property for compatibility with the current API contract.
## Naming and return types
Python methods use `snake_case` and return generated typed models.
```python theme={null}
response = client.agents.list_agents()
agent = response.agents[0]
skills = client.agents.list_agent_skills(agent_id=agent.id)
```
Method arguments are keyword arguments except identifiers that the generated signature marks as positional. Model fields use Python naming while request serialization follows the API schema.
## Async usage
```python theme={null}
from darwin_sdk import AsyncDarwin
client = AsyncDarwin(token="...")
turn = await client.conversations.create_message(
content="Summarize the requests that need attention.",
)
```
Use one async client per application lifecycle. If you provide a custom async HTTP client, its connection limits, proxies, and TLS configuration apply to every resource.
## Failures and retries
The SDK raises generated errors for non-success responses and transport failures. Retries are limited to eligible transient failures; validation or authorization errors are returned immediately. Set a request-specific timeout or retry count only when an operation needs behavior different from the client default.
Retries can repeat a request. Use stable idempotency behavior for create or action methods and do not retry authorization or validation failures blindly.
See [Errors](/errors) for the public error model and [Python and TS Cheat Sheets](/sdks/cheat-sheets) for common method mappings.
# TypeScript SDK Specification
Source: https://docs.darwin.so/sdks/typescript-specification
Client architecture, configuration, resources, retries, and types for the Darwin JavaScript SDK.
The Darwin JavaScript SDK is generated from the reviewed public OpenAPI contract and ships TypeScript types. This page defines the client surface and runtime behavior; use the [API reference](/api-reference/introduction) for endpoint schemas.
## Client
```typescript theme={null}
import { DarwinClient } from '@darwinso/sdk';
const darwin = new DarwinClient({ token: process.env.DARWIN_API_KEY! });
```
Create one `DarwinClient` per service configuration and reuse it. Resource clients are exposed lazily from the root client.
## Configuration
The generated client supports:
* `token` — a bearer token or token provider
* `environment` or `baseUrl` — production by default, or an explicit API origin
* `timeoutInSeconds` — the default request timeout
* `maxRetries` — the default retry ceiling
* `headers` — additional headers sent with every request
* logging and fetch customization supported by the generated runtime
```typescript theme={null}
const darwin = new DarwinClient({
token: process.env.DARWIN_API_KEY!,
timeoutInSeconds: 20,
maxRetries: 2,
headers: { 'X-Request-Source': 'worker' },
});
```
## Resource clients
| Property | Purpose |
| --------------- | ----------------------------------------------------------------------- |
| `account` | Authenticated account and plan context |
| `agents` | Agents, skills, assets, teams, access, and integrations |
| `requests` | Inbound requests and decisions |
| `conversations` | Account-routed and agent-scoped messages |
| `goals` | Outcomes, state changes, and publication requests |
| `deals` | Commercial terms, decisions, and payments |
| `applications` | Darwin Connect applications, enrollment, service accounts, and webhooks |
The public product name is **Connect**; `applications` remains the generated client property for compatibility with the current API contract.
## Naming and return types
JavaScript methods use `camelCase`. Request and response objects are fully typed from the OpenAPI schema.
```typescript theme={null}
const response = await darwin.agents.listAgents();
const agent = response.agents[0];
const skills = await darwin.agents.listAgentSkills({
agentId: agent.id,
});
```
Import public models from the package when you need to annotate application boundaries; otherwise let TypeScript infer types from method results.
## Passthrough requests
`darwin.fetch()` uses the SDK's configured authentication and transport behavior for endpoints that are not yet represented by a generated method.
```typescript theme={null}
const response = await darwin.fetch('/api/v1/account');
```
Prefer a generated resource method when one exists because it provides schema validation and typed results.
## Failures and retries
Non-success responses and transport failures raise generated SDK errors. Retries are limited to eligible transient failures; validation or authorization errors are returned immediately. Per-request options can override timeout, retries, headers, or an abort signal.
Retries can repeat a request. Use stable idempotency behavior for create or action methods and do not retry authorization or validation failures blindly.
See [Errors](/errors) for the public error model and [Python and TS Cheat Sheets](/sdks/cheat-sheets) for common method mappings.
# Security
Source: https://docs.darwin.so/security
How Darwin scopes identity, authority, credentials, and requests.
Darwin treats authentication, action authority, and provider credentials as separate concerns.
## Owner-scoped credentials
API keys and MCP sessions resolve to one authenticated Darwin owner. The agent cannot select another user by supplying a user ID, connection ID, or resource ID.
## Action authority
Each consequential action is checked against:
* the authenticated owner and active agent
* the credential's scopes
* assigned skills, assets, and connections
* resource ownership
* any request that requires account attention
* expiration and replay protection
## Provider credentials
External service credentials are resolved at execution time. They are not placed in prompts or returned to clients.
Darwin stores only the connection state needed to apply owner scope, reviewed actions, skill versions, requests, replay protection, and audit checks. See [Connections and skills](/guides/integrations-and-skills).
## Content protection
Darwin minimizes exposed data across account, request, conversation, goal, deal, and application boundaries. Private coordination details are not part of the public API. The selected Agent runtime and configured model provider process the content required to produce a response.
## Tenant-controlled Agent runtime
Enterprise deployments can place the Agent runtime, durable memory, and model-provider account inside a tenant-controlled environment. The runtime still uses Darwin-issued identity, signed turn grants, access policies, requests, and audit records.
Self-hosting the Agent does not self-host the Darwin account and authorization control plane. Darwin retains the minimum records required for interoperability, while private Agent runtime state remains inside the tenant boundary.
Tenant-controlled Agent runtimes are provisioned with Darwin. Contact us to review hosting, model-provider, retention, and data-residency requirements.
## Sensitive actions
Writes and commitments can create a request that needs attention. Accepting that request grants only the specific action that was reviewed.
## Audit and revocation
Allowed, denied, failed, and request-required attempts are recorded with a correlation ID. API keys, connections, and grants can be revoked independently.