> ## Documentation Index
> Fetch the complete documentation index at: https://docs.devin.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# API Release Notes

> Track changes, new features, and improvements to Devin's APIs

This page tracks changes specific to Devin's APIs (v1, v2, and v3). For application feature releases, see [Application Release Notes](/release-notes/overview).

## 2026

<Update label="March 2026">
  **v3 API Updates**

  * **Session insights generate endpoint (Mar 11)**: Added `POST /v3/organizations/{org_id}/sessions/{devin_id}/insights/generate` and `POST /v3/enterprise/sessions/{devin_id}/insights/generate` endpoints for triggering on-demand session insights generation. Returns `{ "status": "started" }` when generation begins, or `{ "status": "already_exists" }` if insights are already generated or in progress. Poll the existing GET insights endpoint to retrieve results. Requires `ManageOrgSessions` permission.
</Update>

<Update label="February 2026">
  **v3 API Updates**

  * **v3 endpoints promoted to prod**: The following endpoint groups have been promoted from `v3beta1` to `v3` (prod). Update your base URLs from `/v3beta1/` to `/v3/` for these endpoints:

    * Sessions (create, list, get, messages, archive, terminate, tags, insights) — both enterprise and organization scopes
    * Knowledge notes — both enterprise and organization scopes
    * Playbooks — both enterprise and organization scopes
    * Secrets — organization scope
    * Schedules — organization scope
    * Attachments — organization scope
    * Audit logs — both enterprise and organization scopes
    * Consumption & billing (cycles, daily breakdowns, ACU limits) — enterprise scope
    * Metrics (DAU, WAU, MAU, PRs, sessions, searches, active users, usage) — enterprise scope
    * Organizations, users, members, roles, IDP groups — enterprise scope
    * Git connections & permissions — enterprise scope
    * Hypervisors, queue, IP access lists, org group limits — enterprise scope
    * Session tags (organization default tags) — enterprise scope

    **Still in beta** (`v3beta1`): Repository indexing endpoints, service user provisioning endpoints, and guardrail violations endpoints remain on `v3beta1` and are marked with a Beta tag in the docs.

  * **Guardrail violations endpoint**: Added `GET /v3beta1/enterprise/guardrail-violations` and `GET /v3beta1/enterprise/organizations/{org_id}/guardrail-violations` endpoints for querying guardrail violations across the enterprise. Returns violation details including the guardrail type, reasoning, confidence score, action taken, and the triggering message. Supports filtering by `session_id` and `guardrail_id`, with time range and cursor-based pagination. Use the per-org endpoint to filter by organization. Requires `ManageEnterpriseSettings` permission.

  * **IP access list endpoints (Feb 9)**: Added `GET /v3beta1/enterprise/ip-access-list`,`PUT /v3beta1/enterprise/ip-access-list`, and `DELETE /v3beta1/enterprise/ip-access-list` endpoints for managing enterprise IP allowlists. The PUT endpoint replaces the entire list with the provided IP ranges (CIDR notation supported). Requires `ManageEnterpriseSettings` permission.

  * **Scheduled sessions endpoints (Feb 3)**: Added organization-level schedule management endpoints: `POST /v3beta1/organizations/{org_id}/schedules` for creating schedules, `GET /v3beta1/organizations/{org_id}/schedules` for listing schedules, `GET /v3beta1/organizations/{org_id}/schedules/{schedule_id}` for retrieving a specific schedule, `PATCH /v3beta1/organizations/{org_id}/schedules/{schedule_id}` for updating schedules, and `DELETE /v3beta1/organizations/{org_id}/schedules/{schedule_id}` for deleting schedules. Requires `ManageOrgSchedules` permission.
</Update>

<Update label="January 2026">
  **v3 API Updates**

  * **ACU limits endpoints (Jan 27)**: Added enterprise ACU limit management endpoints for Devin sessions: `GET /v3beta1/enterprise/consumption/acu-limits/devin` to retrieve limits, `PUT .../organizations/{org_id}` to set org-level limits, and `DELETE` to remove limits. Requires `ManageBilling` permission.

  * **Attachments endpoints (Jan 27)**: Added organization attachment endpoints: `POST /v3beta1/organizations/{org_id}/attachments` for uploading attachments and `GET /v3beta1/organizations/{org_id}/attachments/{uuid}/{name}` for downloading attachments. Upload requires `UseDevinSessions` permission, download requires `ViewOrgSessions` permission.

  * **Queue endpoint (Jan 21)**: Added `GET /v3beta1/enterprise/queue` endpoint for enterprise admins to monitor session queue health. Returns the total number of queued sessions and a status indicator (`normal`, `elevated`, or `high`). Useful for setting up alerts for capacity issues. Requires `ViewAccountMetrics` permission.

  * **Sessions endpoints (Jan 19)**: Added `GET /v3beta1/enterprise/sessions/{devin_id}` and `GET /v3beta1/organizations/{org_id}/sessions/{devin_id}` endpoints for retrieving details of a specific session. Added `POST /v3beta1/enterprise/sessions/{devin_id}/messages` and `POST /v3beta1/organizations/{org_id}/sessions/{devin_id}/messages` endpoints for sending messages to active sessions (sessions are automatically resumed if suspended). Also added `origins` filter parameter to the sessions list endpoints for filtering by session origin (`webapp`, `slack`, `teams`, `api`, `linear`, `jira`, `other`).

  * **Audit logs order parameter (Jan 17)**: Added `order` query parameter (`asc` or `desc`, defaults to `desc`) to the enterprise and organization audit logs endpoints for controlling the sort order of results.

  * **Secrets router (Jan 16)**: Added organization-level secrets management endpoints: `GET /v3beta1/organizations/{org_id}/secrets` for listing secrets, `POST /v3beta1/organizations/{org_id}/secrets` for creating secrets, and `DELETE /v3beta1/organizations/{org_id}/secrets/{secret_id}` for deleting secrets. Requires `ManageOrgSecrets` permission.

  * **Audit logs fix (Jan 15)**: Fixed an issue where `end_cursor` was not returned in audit logs API responses when there were items on the page.

  * **Service user provisioning (Jan 14)**: Added `POST /v3beta1/enterprise/service-users` and `POST /v3beta1/organizations/{org_id}/service-users` endpoints for programmatically provisioning new service users. Enforces privilege escalation prevention: the target role's permissions must be a subset of the caller's permissions, and `ManageServiceUsers` permissions can never be granted. Requires `ManageAccountServiceUsers` or `ManageOrgServiceUsers` permission respectively.

  * **IDP Groups enterprise-level endpoints (Jan 14)**: Added `GET /v3beta1/enterprise/idp-groups` for listing IDP groups registered with an enterprise, `POST /v3beta1/enterprise/idp-groups` for bulk registering IDP groups (up to 100 at a time), and `DELETE /v3beta1/enterprise/idp-groups/{idp_group_name}` for removing a registered IDP group. Groups with existing role assignments or user memberships cannot be deleted. Requires `ManageAccountMembership` permission.

  * **Audit log actions (Jan 12)**: Added `create_join_request`, `automatic_join_event`, and `reject_join_request` action types to audit log responses.

  * **Active users endpoint (Jan 8)**: Added `GET /v3beta1/enterprise/metrics/active-users` endpoint for retrieving unique active users for a custom date range. Unlike the DAU/WAU/MAU endpoints which return lists broken down by period, this endpoint returns a single count of unique active users across the entire specified range. Supports filtering by organization IDs and configurable activity thresholds (`min_sessions`, `min_searches`).

  * **Hypervisors default status (Jan 8)**: The `GET /v3beta1/enterprise/hypervisors` endpoint now defaults to filtering by `available` status instead of returning all hypervisors. Pass `status=all` to retrieve hypervisors regardless of status.

  * **Session secrets (Jan 5)**: Added `session_secrets` parameter to the session creation endpoint (`POST /v3beta1/organizations/{org_id}/sessions`). Session secrets are temporary secrets available only within the current session and are not stored in organization secrets.

  * **Pagination fix (Jan 5)**: Fixed pagination bug in the v3 Enterprise Users API where `end_cursor` was not always returned correctly.

  **v2 API Updates**

  * **Repo cloning fix (Jan 20)**: Fixed the `POST /v2/enterprise/organizations/{org_id}/clone-repository` endpoint schema. Removed the legacy `RepoSetupStepsT` format and simplified the request body to use flat fields (`pull_repo_commands`, `run_lint_commands`, `run_project_commands`, `update_dependencies_commands`, `repo_note`, `repo_path`).

  * **Git permissions URL fields (Jan 15)**: Added `group_prefix_url` and `repo_url` fields to the `GitPermissionRequest` schema, providing full URL alternatives to path-based repository and group prefix matching.

  * **Organization member role field (Jan 8)**: Added `org_role_name` field to the `GET /v2/enterprise/organizations/{org_id}/members` response, showing each member's role within the organization.

  * **Organization creation option (Jan 8)**: Added `add_creator_as_member` boolean parameter (defaults to `true`) to `POST /v2/enterprise/organizations`, allowing enterprise admins to create organizations without automatically adding themselves as a member.

  * **Consumption timezone documentation (Jan 7)**: Added timezone behavior documentation to the daily consumption endpoints. Billing cycles use midnight PST (08:00:00 UTC) as the day boundary.

  **v1 API Updates**

  * **Secret types update (Jan 16)**: Added `dictionary` as a recognized secret type value in the secrets API schema. Note: creating secrets with type `dictionary` is deprecated; use `cookie`, `key-value`, or `totp` instead.
</Update>

## 2025

<Update label="December 2025">
  **v3 API Updates**

  * **Org group limits endpoint (Dec 23)**: Added `GET /v3beta1/enterprise/org-group-limits` and `PUT /v3beta1/enterprise/org-group-limits` endpoints for managing organization group configurations. Groups map sets of organization IDs to optional max Agent Compute Unit limits per billing cycle. Requires `ManageOrganizations` permission. *This feature requires enablement by your account team.*
  * **Session archive endpoint (Dec 11)**: Added `POST /v3beta1/organizations/{org_id}/sessions/{devin_id}/archive` endpoint for archiving sessions. Also added `archive` query parameter to `DELETE /v3beta1/organizations/{org_id}/sessions/{devin_id}` (terminate session) and `is_archived` field to session responses.
  * **Order parameter removal (Dec 11)**: **Breaking change:** Removed the `order` query parameter from the sessions list endpoint (`GET /v3beta1/organizations/{org_id}/sessions`). Clients must stop sending `order`; use cursor-based pagination with `first`/`after` parameters instead.
  * **Searches router (Dec 10)**: Added enterprise and organization-level search endpoints at `GET /v3beta1/enterprise/searches` and `GET /v3beta1/organizations/{org_id}/searches` for listing searches with pagination and filtering.
  * **Audit logs improvements (Dec 10)**: Added `data` object, `service_user_name`, and `user_email` fields to audit log responses. Added `update_git_permission` action type.
  * **Advanced sessions support (Dec 8)**: Added new request parameters for advanced session workflows: `child_playbook_id`, `session_links`, and `bypass_approval`. Session responses now include `child_session_ids`, `parent_session_id`, and `is_advanced` fields.
  * **Session Tags router (Dec 5)**: Added CRUD endpoints at `/v3/beta/enterprise/organizations/{org_id}/tags` for managing allowed session tags per organization. When tag validation is enabled, session creation and tag updates enforce tags from the allowed list.
  * **Enterprise Sessions endpoint (Dec 5)**: Added `GET /v3/beta/enterprise/sessions` to list sessions across the enterprise with optional `org_ids` filtering.
  * **Git Permissions updates (Dec 5)**: Added `prefix_path` field for matching repositories by path prefix. Added `PUT` and `DELETE` endpoints for bulk replacing or clearing all permissions for an organization.
  * **Session impersonation (Dec 5)**: Added `create_as_user_id` parameter to the session creation endpoint, allowing service users to create sessions on behalf of other users.
  * **Hypervisors response change (Dec 5)**: The hypervisors endpoint response now returns `utilization_percentage` instead of `max_slots` and `available_slots`.
  * **Notes and Playbooks routers (Dec 1)**: Added enterprise and organization-level Notes and Playbooks management endpoints to v3 API. Notes endpoints require `ManageAccountKnowledge` permission, Playbooks endpoints require `ManageAccountPlaybooks` permission.

  **v2 API Updates**

  * **Org group limits endpoint (Dec 23)**: Added `GET /v2/enterprise/org-group-limits` and `PUT /v2/enterprise/org-group-limits` endpoints for managing organization group configurations. Groups map sets of organization IDs to optional max Agent Compute Unit limits per billing cycle. The PUT endpoint replaces the entire configuration (groups not in the request are deleted). *This feature requires enablement by your account team.*
  * **Self endpoint (Dec 23)**: Added `GET /v2/enterprise/self` endpoint returning information about the authenticated API key, including the key ID, associated user ID, user email, and organization ID.
  * **Sessions messages field (Dec 11)**: Added `messages` field to v2 sessions API response, providing all session messages similar to the v1 API.
  * **Response schema improvements (Dec 11)**: Added proper response schemas for audit logs, snapshots, and playbook endpoints including `AuditLogsResponse`, `EnterpriseSnapshotResponse`, and `EnterprisePlaybookResponse`.

  **v1 API Updates**

  * **Audit logs deprecation (Dec 5)**: The `/v1/audit-logs` endpoint is deprecated; use the v2 or v3 audit logs endpoints instead.
</Update>

<Update label="November 2025">
  **v2 Enterprise API Updates**

  * **Pagination limit update (Nov 21)**: Maximum pagination limit reduced from 1000 to 200 items per request for improved performance and reliability. Default limit remains 100. This change does NOT affect the v1 External API.
  * **Sessions router (Nov 16)**: Added comprehensive sessions management endpoints to v2 API for enterprise administrators.
  * **Snapshots API endpoint (Nov 3)**: Added endpoint for retrieving snapshot details programmatically.

  **v1 API Updates**

  * **Terminate session endpoint (Oct 31)**: Added endpoint to terminate running sessions programmatically.
</Update>

<Update label="October 2025">
  **v3 API Launch (Beta)**

  * **API v3 launch (Oct 23)**: Launched v3 API with full RBAC support, service user authentication model, and comprehensive audit logging for service user actions.

  **v2 Enterprise API Updates**

  * **Snapshot creation endpoint (Oct 30)**: New V2 Enterprise Organizations API endpoint for enterprise admins to programmatically clone repositories and create snapshots with custom setup steps and startup commands.
  * **Playbooks API improvements (Oct 14)**: Added API for publishing enterprise playbooks with improved functionality for programmatic playbook management.
</Update>

<Update label="September 2025">
  **v2 Enterprise API Updates**

  * **Roles router (Sep 25)**: Added enterprise roles router with five API endpoints for managing roles programmatically.

  **v1 API Updates**

  * **Playbooks API (Sep 6)**: Added comprehensive Playbooks API endpoints to v1 for creating, updating, listing, and deleting playbooks programmatically.
  * **Secrets endpoint (Sep 5)**: Added new `POST /v1/secrets` endpoint for creating secrets via API.
</Update>

<Update label="March 2025">
  **v2 Enterprise API Launch**

  * **API v2 launch (Mar 23)**: Launched Enterprise API v2 for enterprise administrators with organization management, consumption tracking, and member management capabilities.
</Update>

## 2024

<Update label="October 2024">
  **v1 API Launch (Oct 26)**

  * Launched REST API for programmatic session creation and management
  * Session creation, monitoring, and management endpoints
  * File attachment upload and download support
  * Basic authentication with API keys
  * Idempotent session creation support
  * Use cases: automatic PR reviews, lint error resolution, migrations
</Update>

***

## API Versioning Policy

### Backward Compatibility

We strive to maintain backward compatibility within major versions. Breaking changes will be:

1. Announced at least 7 days in advance
2. Documented in these release notes
3. Accompanied by migration guides when applicable

### Deprecation Process

When we deprecate an API feature:

1. **Announcement**: We'll announce the deprecation with a timeline
2. **Deprecation Period**: The feature remains available but marked as deprecated
3. **Removal**: The feature is removed after the deprecation period

### Version Support

* **v1**: Legacy — will be deprecated soon in favor of the Organization API (v3)
* **v2**: Legacy — will be deprecated soon in favor of the Enterprise API (v3)
* **v3**: Generally available, recommended for all new integrations

***

## Migrating to the current API

For step-by-step migration instructions from v1 or v2, see the [Migration guide](/api-reference/getting-started/migration-guide).

## Support

For questions about API changes or migration assistance, email [support@cognition.ai](mailto:support@cognition.ai).