How to Use the Devin API to Create Sessions and Automate Workflows

A study of more than 700,000 pull requests found that PRs wait an average of 4 days to get reviewed. Large changes (500 or more lines) take about 9 days to merge. That delay is why teams look past the Devin AI web UI and ask how to drive sessions from GitHub Actions, ticket systems, and internal tools. The Devin API is the REST interface for that work: create sessions, manage knowledge and playbooks, and operate organization or enterprise resources with credentials you can rotate and audit.

The Devin API is a REST interface for creating and managing Devin sessions, knowledge, playbooks, and enterprise resources using service-user credentials. Official docs now put v3 at the center. Older v1 and v2 routes still work during deprecation, but they do not receive new features. New integrations should use service users with cog_ keys, not personal legacy keys that third-party posts still emphasize.

That shift is the content gap this guide fills. Many tutorials stop at "paste a personal API key and POST a prompt." Official v3 design expects:

1. A service user (non-human principal) with a role
2. A Teams or Enterprise path depending on org shape
3. Session creation under /v3/organizations/{org_id}/sessions
4. Explicit handling of 4xx and 429 responses

Devin AI itself is Cognition's autonomous coding agent. The API does not replace the agent; it is how you start, attribute, and operate agent work at pipeline scale. The rest of this article walks through setup, session lifecycle calls, org versus enterprise scopes, migration from v1/v2, and a practical pattern for storing the files and notes Devin produces so humans can review them later.

Devin's authentication model separates principal (who you are) from token (how you prove it). For automation, the principal is a service user. The token is a service user API key that starts with cog_. You send it on every request:

curl -X GET "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions" \
  -H "Authorization: Bearer $DEVIN_API_KEY"

How to get a Devin API key (v3)

For a standard organization (the Teams path):

1. Open Settings > Service users in your Devin organization.
2. Click Create service user and give it a clear name such as ci-pipeline or pr-review-bot.
3. Assign a role. Use Member for most automation that creates sessions and manages knowledge, playbooks, and secrets. Use Admin only when the bot must change org settings or impersonate users.
4. Click Generate API key, copy the cog_ value immediately (it is shown once), and store it in a secret manager or CI secret store.
5. Copy your organization ID from the same Service Users page into DEVIN_ORG_ID.

export DEVIN_API_KEY="cog_your_key_here"
export DEVIN_ORG_ID="your_org_id"

That is the modern answer to "How do I get a Devin API key?" Legacy keys under Settings > API Keys still exist for v1/v2 (apk_user_ personal keys and apk_ service keys), but docs mark them deprecated for new work.

What a Devin service user is A service user is a non-human account built for integrations. It has its own identity in audit logs, its own role, and its own membership scope. It is not a human login with a personal key bolted onto a script. That design matters when you need least privilege, key rotation, and a clear split between "bot started this session" and "Alice started this session."

• Service user with a service user API key (cog_): CI/CD, bots, and production automation
• Human user with a Personal Access Token (cog_, closed beta): local scripts under your own identity

Personal Access Tokens (PATs) are in closed beta and are not the default path for org automation. Contact Cognition support if you need PAT access. For pipelines, service users remain the documented recommendation.

Session attribution with create_as_user_id

By default, a session created with a service user key is attributed to that service user. To create a session on behalf of a human (so it appears in their session list and counts toward their usage), pass create_as_user_id:

curl -X POST "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions" \
  -H "Authorization: Bearer $DEVIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Fix the login bug in issue #42",
    "create_as_user_id": "user_abc123"
  }'

Impersonation requires the ImpersonateOrgSessions permission. On Teams orgs, that effectively means the Admin role on the service user. User IDs come from the List users endpoint or organization member settings in the UI.

In v1/v2, personal keys automatically attributed sessions to the human. In v3, you get the same product behavior with explicit attribution plus RBAC and centralized keys. That is the main reason third-party guides that only teach personal keys fall short for production.

Keep Devin session artifacts in one reviewable workspace

Give agents and humans a shared Fast.io workspace with version history, Intelligence Mode search, and MCP access so API-driven Devin runs leave more than a closed sandbox. Start with a 14-day free trial.

Start 14-Day Trial

Most integrations need four operations: create a session, list sessions, send a follow-up message, and optionally seed knowledge so Devin AI follows team conventions.

Create a session

curl -X POST "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions" \
  -H "Authorization: Bearer $DEVIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Create a simple Python script that prints Hello World"}'

A successful create returns session identifiers you store for later message and status calls. Keep the prompt specific: repository context, acceptance criteria, and hard rules (for example, "never push to main") reduce thrash.

List sessions

curl "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions" \
  -H "Authorization: Bearer $DEVIN_API_KEY"

Pagination on v3 is cursor-based (first + after), not the older offset model. When you page large result sets, read end_cursor from the response and pass it as after on the next request.

Send a message to a running session

export SESSION_ID="your_session_id"

curl -X POST "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions/$SESSION_ID/messages" \
  -H "Authorization: Bearer $DEVIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Please also add unit tests"}'

Follow-up messages are how you turn a one-shot job into a multi-step operator loop without starting a new session for every correction.

Knowledge notes

Knowledge entries teach Devin conventions that should apply across sessions:

curl -X POST "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/knowledge/notes" \
  -H "Authorization: Bearer $DEVIN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Coding standards",
    "trigger_description": "When writing code",
    "body": "Use TypeScript strict mode. Prefer pure functions for parsers."
  }'

Playbooks and secrets live under the same organization scope (/playbooks, /secrets). Treat them like infrastructure: named, version-controlled definitions in git when possible, with secrets only in Devin's secret store or your external vault.

A practical CI-shaped flow

Cognition's public walkthrough for automated PR review still shows the product pattern clearly, even though older examples used /v1/sessions: on pull_request, collect changed files, craft a review-only prompt with guardrails (no commits, limited comments), then create a Devin session. On v3 you keep that event shape and change auth and base path:

• Secret name stays something like DEVIN_API_KEY, but the value is a cog_ service user key.
• Endpoint becomes POST /v3/organizations/{org_id}/sessions.
• Optional create_as_user_id attributes the review to an eng lead or bot owner for usage reporting.

Cognition notes that automated review often finishes in about five to ten minutes and should stay an extra set of eyes, not a full replacement for human review. That matches how you should wire status checks: wait for comments, fail closed only when your policy requires it, and never merge solely because the bot finished.

Featured path in four steps

1. Create a service user and generate a cog_ key.
2. Choose Teams vs Enterprise (single org vs multi-org RBAC and cross-org admin).
3. Create a session with a tight prompt (and create_as_user_id when you need human attribution).
4. Handle 4xx and 429 with clear retries and permission fixes (next section).

Official docs split the Devin API into two scopes. Confusing them is a common source of 403 and 404 errors.

Organization API

Base URL: https://api.devin.ai/v3/organizations/*

Use this scope for day-to-day automation inside one organization:

• Sessions
• Knowledge notes
• Playbooks
• Secrets
• Other org-local resources

Most product integrations start here. The Teams quick start is written for this path.

Enterprise API

Base URL: https://api.devin.ai/v3/enterprise/*

Use this scope for cross-organization management:

• Analytics and consumption
• Audit logs
• User and role management
• Billing-related operations
• Infrastructure and multi-org admin tasks

Enterprise customers can create service users at two levels:

• Organization scope (Settings > Service users): access to /v3/organizations/{org_id}/* for sessions and org resources
• Enterprise scope (Enterprise settings > Service users): access to /v3/enterprise/* plus org routes for cross-org ops and analytics

An enterprise service user with enterprise-level permissions inherits corresponding org-level permissions across all organizations. That is powerful and easy to over-scope. Prefer an org-scoped service user when the bot only needs one org.

Example enterprise calls:

# List organizations
curl "https://api.devin.ai/v3/enterprise/organizations" \
  -H "Authorization: Bearer $DEVIN_API_KEY"

# Daily consumption (Unix timestamps)
curl "https://api.devin.ai/v3/enterprise/consumption/daily?time_after=1735689600&time_before=1738368000" \
  -H "Authorization: Bearer $DEVIN_API_KEY"

# Audit logs
curl "https://api.devin.ai/v3/enterprise/audit-logs" \
  -H "Authorization: Bearer $DEVIN_API_KEY"

Dedicated Devin Enterprise deployments replace api.devin.ai with a custom domain such as api.your-company.devinenterprise.com. Confirm the host with your admin before shipping clients.

Which path should you choose?

• Teams / standard org: one organization, Member or Admin roles, Organization API. Start with the Teams quick start.
• Enterprise: multiple organizations, custom roles, fine-grained RBAC, cross-org analytics. Use the Enterprise quick start and assign only the permissions each endpoint documents (for example UseDevinSessions, ManageOrgSecrets, ViewAccountMetrics).

Every endpoint is gated by a named permission. If create-session returns 403, the fix is almost never "try a different base URL." Fix the service user's role first.

Official docs document standard HTTP status codes for all API surfaces:

• 200 / 201: Success or created. Proceed and store IDs from the body.
• 400 Bad Request: Fix payload shape, required fields, or invalid IDs.
• 401 Unauthorized: Check Authorization: Bearer ..., key prefix, and whether the key was revoked.
• 403 Forbidden: Role lacks the endpoint permission, or key type does not match the route.
• 404 Not Found: Wrong org ID, session ID, or host.
• 429 Too Many Requests: Back off with jitter; reduce parallel session spam.
• 500 Internal Server Error: Retry with limits; escalate to support@cognition.ai if it persists.

Troubleshooting notes that matter in practice

• 401 with a "valid" key: You may be sending a legacy apk_ or apk_user_ key to a v3-only surface (including Devin MCP, which expects cog_ keys). Generate a service user key.
• 403 on create_as_user_id: The service user lacks ImpersonateOrgSessions. Raise the role or stop impersonating.
• 404 on sessions: Confirm DEVIN_ORG_ID and that the session belongs to that org. Dedicated enterprise hosts use a different base domain.
• 429 under CI fan-out: Do not create one Devin session per file in a monorepo PR. Batch the review into one prompt, or gate on labels so only high-risk PRs spawn sessions.

Migrating from v1/v2

Cognition's migration guide maps the mechanical changes:

• Auth: apk_user_ / apk_ keys become service user cog_ tokens
• Base URL: /v1/* and /v2/* become /v3/organizations/* and /v3/enterprise/*
• Pagination: offset + limit becomes cursor-based first + after
• Permissions: key-level all-or-nothing becomes role-based granular permissions

Session route mapping:

• Create: POST /v1/sessions → POST /v3/organizations/{org_id}/sessions
• List: GET /v1/sessions → GET /v3/organizations/{org_id}/sessions
• Get: GET /v1/session/{session_id} → GET /v3/organizations/{org_id}/sessions/{devin_id}
• Message: POST /v1/session/{session_id}/message → POST /v3/organizations/{org_id}/sessions/{devin_id}/messages

Knowledge, playbooks, and secrets follow the same org-scoped pattern. Enterprise-only endpoints (audit logs, consumption, multi-org members, roles) have no v1/v2 twin.

Deprecation is already active: legacy keys keep working for a transition window, new orgs may not get legacy key creation, and end of life is described as coming soon. Migrate when you can still run both side by side.

Security baseline for production keys

Official auth guidance is direct:

1. Store keys in environment variables or a secret manager, never in git or client code.
2. Rotate on a schedule; revoke immediately on leak.
3. Prefer service users over personal keys for automation.
4. Grant least privilege roles.
5. Watch enterprise audit logs for unexpected call patterns.

That checklist is enough for most teams until compliance requirements force a deeper control plane.

The Devin API solves orchestration: who can start work, under which identity, with which permissions. It does not solve durable team storage after a session ends. Session sandboxes are great for isolation. They are a weak archive for design docs, patch notes, exported diffs, screenshots, and the human review trail that still has to happen after Devin AI finishes.

Teams often start with local disks, git branches alone, object storage such as S3, or shared drives like Google Drive and Dropbox. Those options work until you need concurrent agent and human access, per-file version history, and searchable context without standing up a separate vector database.

Fast.io is built as an intelligent workspace for agentic teams, not as a Devin feature. Use it beside Devin:

• Store prompts, playbook markdown, and final PR write-ups in an org-owned workspace with granular permissions.
• Enable Intelligence Mode so files are indexed for hybrid search (full-text, semantic, and metadata filters) when reviewers ask "what did the bot change last week?"
• Use the consolidated MCP toolset over Streamable HTTP at /mcp (legacy SSE at /sse) so other agents and scripts can read and write the same workspace. Docs live at mcp.fast.io/skill.md.
• Keep an append-only audit log of who uploaded what and when, separate from Devin's own enterprise audit endpoints.
• Hand ownership from the bot account to a human when the automation is ready for long-term team use, while retaining admin as needed.

A concrete pattern looks like this:

1. CI authenticates to Devin with a service user and creates a session for the PR or ticket.
2. Devin produces a branch, comments, and a short report.
3. Your job posts the report, links, and any exported artifacts into a Fast.io workspace (or your existing S3/Drive bucket if that is already the team standard).
4. Reviewers open the workspace, use search or chat over indexed files, leave approvals, and keep version history when the next bot run overwrites the report.

Fast.io plans start at Starter $29/mo, Business $99/mo, and Growth $299/mo. Every organization begins with a 14-day free trial (credit card required). Paid org subscriptions are required for real work after the trial. That pricing is for the workspace layer around Devin AI, not for Devin itself. Check devin.ai/pricing for Devin product plans.

If you are wiring agents more broadly, start from storage for agents and the product overview for AI features. The goal is simple: Devin API for session control, shared workspace for durable human-agent handoff.