@kentcdodds/devin

@kentcdodds/devin

Intent

SDK for the Devin v3 API so Kody can start, monitor, and message Devin sessions and manage the org's knowledge notes, playbooks, schedules, and PR reviews. Transport is one compact authenticated helper against https://api.devin.ai (Bearer {{secret:devinServiceUserKey}}), scaffolded from Devin's official v3-openapi.yaml.

Deliberately v3 only: legacy apk_ v1/v2 keys return 403 against /v3/*. Fork it if you want your own Devin automation surface — see If you forked this package.

When To Use

• Start a Devin session and follow it (status, messages, PRs, structured output).
• Audit recent org sessions, their ACU burn, tags, and insights.
• Manage knowledge notes, playbooks, and scheduled sessions.
• Trigger or check a Devin PR review.
• Call any unwrapped Devin endpoint via devinRequest.

Required setup

• Secret devinServiceUserKey (user scope, host api.devin.ai): a v3 service user API key (cog_…) from Devin Settings → Devin API. Provision a service user with organization scope; grant ImpersonateOrgSessions if sessions should be attributed to a human user via createAsUserId.
• Value devinOrgId: the org-… id every /v3/organizations/... path is scoped to. Read once per runtime; every helper also takes an orgId override.

Endpoint access is RBAC-gated on the service user's role, so a 403 usually means a missing permission rather than a bad key. whoami() is the cheapest check.

If you forked this package

Nothing here is account-specific — the secret name, the value name, and the org id are all resolved at runtime:

1. Save a devinServiceUserKey secret (user scope) with api.devin.ai approved as an allowed host.
2. Save a devinOrgId value with your org-… id, or pass orgId to every helper if you work across several orgs.
3. Adopt the fork (or approve its secret access), then smoke-test with the read-only ./self export — it proves credential, host, and RBAC in one call.

Rename the secret by editing DEVIN_SECRET_NAME and the placeholder in src/lib/client.ts; both live in that one file.

Exports

Default exports: ./self → whoami; ./sessions → listSessions; ./knowledge → listNotes; ./playbooks → listPlaybooks; ./schedules → listSchedules; ./reviews → getPrReview; ./usage → dailyConsumption; ./request → devinRequest.

Cost and safety

createSession, createPrReview, and generateSessionInsights consume ACUs. terminateSession destroys a session's VM, and deleteNote / deletePlaybook / deleteSchedule are irreversible — confirm intent (and the id) first. Prefer updateSchedule({ enabled: false }) over deleting a schedule.

Example

import { createSession, getSessionStatus, sendMessage } from 'kody:@kentcdodds/devin/sessions'

const session = await createSession({
  prompt: 'Fix the flaky auth test in kentcdodds/kody and open a PR',
  repos: ['kentcdodds/kody'],
  tags: ['kody'],
  maxAcuLimit: 10,
})

await sendMessage({ devinId: session.session_id, message: 'Also update the changelog' })
const status = await getSessionStatus({ devinId: session.session_id })

Unwrapped endpoints (enterprise admin, code scans, repo indexing, snapshot blueprints, org secrets) via ./request:

import { devinRequest } from 'kody:@kentcdodds/devin/request'

const { status, body } = await devinRequest({
  path: '/v3beta1/organizations/{org_id}/repositories',
})

Notes

• Pagination is cursor based: pass after: page.end_cursor while page.has_next_page, or let listAllSessions walk up to maxPages for you.
• Devin ignores the spec's nested qs object for session filters; list filters are sent as flat, repeated query params (?tags=a&tags=b).
• Schedules are the exception to cursor pagination — they use limit/offset.
• Timestamps are Unix seconds, and scheduledAt is an ISO date-time string.
• getPrReview returns null for an unreviewed PR instead of throwing on 404.
• Helpers throw DevinApiError (with status and body) on non-2xx responses; devinRequest returns { status, body } unwrapped instead.

Devin is a trademark of Cognition AI; community-icon.svg uses their mark to identify the API this package wraps. This package is unofficial.