RonanCodes/devin

Devin

Drive Devin (Cognition's autonomous AI software engineer) over its API: hand a session a natural-language prompt (+ repos, attachments, a structured-output schema), poll until it finishes, and read back the PR. Two shapes: dispatch-and-get-a-PR (CLI/CI), and embed-in-app (your backend creates + steers sessions on behalf of users).

Target the v3 org-scoped API. A cog_ key and an org-... id are v3 artefacts. The /v1/sessions shape most blog posts show still works but is deprecated and gets no new features. v3 paths put the org id in the path: /v3/organizations/{org_id}/....

Usage

/ro:devin install       # env check + a fetch helper
/ro:devin dispatch       # create a session from a prompt (CLI / one-shot)
/ro:devin poll           # poll a session to terminal + read the PR
/ro:devin embed          # create + steer sessions from an app backend (Worker)
/ro:devin ops            # API-ops cheat-sheet (curl)

Prerequisites

• Keys in ~/.claude/.env (megathon block): DEVIN_API_KEY (cog_..., 90-day service admin), DEVIN_ORG_ID (org-...).
• Devin's GitHub/GitLab integration connected at org level + the target repo connected, before a session can touch it.
• ACU budget awareness (see Gotchas) — always cap with max_acu_limit.

Auth (API-ops core)

• Base URL: https://api.devin.ai
• Header: Authorization: Bearer $DEVIN_API_KEY + Content-Type: application/json
• Org paths: https://api.devin.ai/v3/organizations/{org_id}/... (the cog_ key is org/enterprise-scoped; enterprise scope can also hit org paths).
• Failures: 401 bad key, 403 insufficient role, 404 bad path (e.g. missing {org_id}), 429 rate-limited (specific limits unpublished, back off).

| Purpose | Method + path (v3) | | --- | --- | | Create session | POST /v3/organizations/{org_id}/sessions | | Get session | GET /v3/organizations/{org_id}/sessions/{devin_id} | | List sessions | GET /v3/organizations/{org_id}/sessions (cursor paginated) | | Message a session | POST /v3/organizations/{org_id}/sessions/{devin_id}/messages | | Terminate | DELETE /v3/organizations/{org_id}/sessions/{devin_id} | | Enterprise consumption | GET /v3/enterprise/consumption/daily?time_after=...&time_before=... | | Enterprise audit / members | GET /v3/enterprise/audit-logs, /v3/enterprise/members/users |

No official SDK is confirmed (docs show only curl + raw Python requests). Treat any devin-sdk / @cognition/devin-core package as unverified, build against REST. Plain fetch from a Worker works.

install

# ~/.claude/.env already has DEVIN_API_KEY + DEVIN_ORG_ID
echo "$DEVIN_API_KEY" | grep -q '^cog_' && echo "v3 key OK"

dispatch (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": "Fix the login bug in issue #42 and open a PR",
    "repos": ["<repo-id>"],
    "max_acu_limit": 10,
    "title": "Auth login fix"
  }'

Response (200) includes session_id, url (app.devin.ai/sessions/...), status: "new", pull_requests[], structured_output, acus_consumed. Persist session_id.

Key create-session body params: prompt (required), repos[], max_acu_limit (budget circuit-breaker, set it), structured_output_schema (JSON Schema Draft 7, ≤64KB, self-contained, no external $ref), structured_output_required (force a final structured result), attachment_urls[], bypass_approval (skip safe-mode approvals, for unattended CI), tags[], title, secret_ids[] / session_secrets[] (private deps), knowledge_ids[], playbook_id, devin_mode (normal|fast|lite|ultra), create_as_user_id (attribute to an end user; needs ImpersonateOrgSessions).

poll (wait for the PR)

status: new → claimed → running → exit (also error, suspended, resuming). Terminal = exit / error / suspended. status_detail adds nuance (working, waiting_for_user, waiting_for_approval, finished; and for suspended: out_of_credits, usage_limit_exceeded, etc., which look like "stopped" but mean "blocked on quota").

SID="devin-..."
while :; do
  s=$(curl -s "https://api.devin.ai/v3/organizations/$DEVIN_ORG_ID/sessions/$SID" \
        -H "Authorization: Bearer $DEVIN_API_KEY")
  st=$(echo "$s" | jq -r .status)
  echo "status=$st acus=$(echo "$s" | jq -r .acus_consumed)"
  case "$st" in exit|error|suspended) break;; esac
  sleep 10
done
echo "$s" | jq '{pr: .pull_requests, out: .structured_output}'

Read the result from the get-session response: pull_requests[].pr_url (+ pr_state), structured_output (if you passed a schema), acus_consumed (cost so far).

Hold two truths: status == "exit" is the stop signal; status_detail == "finished" is an in-running "task done, awaiting more input" signal for interactive sessions. For fire-and-forget, break on exit.

embed (in an app backend)

• Backend holds the cog_ key (never client-side). Create the session from your server (a Worker is fine), store session_id against your domain object (ticket/job/PR).
• Use create_as_user_id to attribute the session to the end user (shows in their list, counts to their usage).
• Steer a live session with POST .../messages ({ "message": "..." }); reflect status + status_detail (waiting_for_user, waiting_for_approval) in your UI.
• Don't hold an HTTP request open for the whole run (sessions run minutes to hours). Kick off, return session_id, reconcile via a poll loop, Worker Cron, a Durable Object alarm, or a queue.

// src/lib/devin.ts — Workers-safe
const BASE = 'https://api.devin.ai/v3/organizations'
export async function createDevinSession(env: Env, prompt: string, repos: string[]) {
  const res = await fetch(`${BASE}/${env.DEVIN_ORG_ID}/sessions`, {
    method: 'POST',
    headers: { Authorization: `Bearer ${env.DEVIN_API_KEY}`, 'Content-Type': 'application/json' },
    body: JSON.stringify({ prompt, repos, max_acu_limit: 10 }),
  })
  if (!res.ok) throw new Error(`Devin create failed: ${res.status} ${await res.text()}`)
  return res.json() as Promise<{ session_id: string; url: string; status: string }>
}

Repo access / scope

Two layers: (1) org-level: Devin's Git integration + the repo must be connected in org settings; (2) per-session: pass repos[] to scope, or name the repo/PR URL in the prompt. Private deps via secret_ids[] (pre-stored) or inline session_secrets[]. Attachments must be referenced in the prompt as a literal ATTACHMENT:"{url}" line (all caps, own line) or Devin ignores them.

Gotchas

1. Cost is ACU-metered and open-ended (~15 min active work per ACU). Vague prompts on big repos burn ACUs fast. Always set max_acu_limit. Devin bills only while actively working.
2. Async + long-running: you poll. No synchronous "return the PR" call. Webhooks are not documented (treat as poll-only). Watch suspended sub-reasons (quota/billing), they aren't "done".
3. Version/path drift is the easy mistake. cog_ key ⇒ v3 org-scoped paths with {org_id} in the path. Targeting v1, or dropping {org_id}, → 404. v3 idempotency flag is unverified; if you need exact-once create, dedupe yourself (store task → session_id).
4. Service-admin key is powerful and org-wide. Apply least privilege; this one is a 90-day key.

Relation to the local/remote factory

Devin is a third-party sibling to the local factory (/ro:ralph, /ro:planner-worker) and the remote Factory app: another way to dispatch a coding task and get a PR. Use it when you want Cognition's agent specifically; otherwise the factory loops run on the Max plan with no per-ACU cost.

Env var summary

DEVIN_API_KEY=cog_...   # v3 service key, server only
DEVIN_ORG_ID=org-...    # goes IN the path

Safety

Server-side only; never expose the cog_ key. Cap every session with max_acu_limit. Use bypass_approval only for deliberately-unattended CI. Review every PR Devin opens before merge (human-in-the-loop, same as the factory).

See also

• Docs: https://docs.devin.ai/api-reference/overview (v3 sessions, usage-examples, billing/ACUs)
• Factory siblings: /ro:ralph, /ro:planner-worker, /ro:night-shift