Skip to main content
The v3 API provides full RBAC support with service user authentication. This is the recommended API for production automation.
The v3 API is currently in beta. Some endpoints may change as we improve the API.
Base URLs:
  • https://api.devin.ai/v3beta1/enterprise/* – endpoints that require enterprise-level permissions
  • https://api.devin.ai/v3beta1/organizations/* – endpoints scoped to a single organization
Authentication: Service User Credentials (Enterprise or Organization level) (learn more)
Some enterprise endpoints operate on specific organizations but are still guarded by enterprise-level permissions. These use paths like /v3beta1/enterprise/organizations/{org_id}/... (for example, GET /v3beta1/enterprise/organizations/{org_id}/audit-logs). Even though they include an org_id path parameter, they still require enterprise-level permissions such as ManageEnterpriseSettings.

​
Permissions and RBAC

Every v3 endpoint is gated by a specific permission assigned to the calling service user’s role. Permissions are split into two scopes: enterprise-level permissions control /v3beta1/enterprise/* endpoints, and organization-level permissions control /v3beta1/organizations/{org_id}/* endpoints. An enterprise service user with an enterprise-level permission automatically inherits the corresponding org-level permission across all organizations.

​
Enterprise permissions

PermissionControls
ReadAccountMetaSelf (granted to all service users by default)
ManageEnterpriseSettingsAudit logs, Organization tags
ManageOrganizationsOrganizations CRUD, Organization group limits
ManageAccountMembershipRoles, Enterprise users, Enterprise IdP groups, Enterprise service user membership, Enterprise IdP group registration
ManageAccountServiceUsersService user provisioning (enterprise)
ManageAccountKnowledgeKnowledge notes (enterprise)
ManageAccountPlaybooksPlaybooks (enterprise)
ManageGitIntegrationsGit connections, Git permissions
ManageBillingConsumption cycles, Daily consumption breakdowns
ViewAccountMetricsUsage metrics (DAU/WAU/MAU, PRs, sessions, searches, active users), Queue status
ViewEnterpriseInfraDetailsHypervisors
ViewAccountSessionsSessions list and detail (enterprise, read-only)
ManageAccountSessionsSend messages to sessions (enterprise)
ViewAccountSearchesSearches (enterprise)

​
Organization permissions

PermissionControls
ManageOrgSecretsSecrets CRUD
ManageOrgKnowledgeKnowledge notes (organization)
ManageOrgPlaybooksPlaybooks (organization)
ManageOrgServiceUsersService user provisioning (organization)
ViewOrgSessionsSessions list and detail (organization, read-only)
ManageOrgSessionsSend messages, terminate, archive sessions
UseDevinSessionsCreate sessions
ImpersonateOrgSessionsCreate sessions on behalf of other users (create_as_user_id)
ViewOrgSearchesSearches (organization)

​
Service user scopes

Enterprise service users authenticate with /v3beta1/enterprise/* endpoints and can operate across all organizations. They are assigned enterprise-level roles and automatically inherit the corresponding org-level permissions in every organization (for example, ViewAccountSessions grants ViewOrgSessions in all orgs). Organization service users are scoped to a single organization and authenticate with /v3beta1/organizations/{org_id}/* endpoints only. They are assigned org-level roles.

​
Creating service users

Service users can be created in two ways:
  1. UI: Enterprise Settings → Service Users — create enterprise or org-level service users with custom roles and generate API tokens.
  2. API: POST /v3beta1/enterprise/service-users or POST /v3beta1/organizations/{org_id}/service-users — programmatically provision service users with a specified role and TTL. The new user’s permissions must be a subset of the caller’s permissions (privilege escalation is prevented).
For token generation and authentication details, see the Authentication Guide.

​
Self

Get information about the authenticated service user:

Get Self

Retrieve information about the authenticated service user

​
Audit Logs

Access comprehensive audit trails:

Enterprise Audit Logs

Get enterprise-wide audit logs

Organization Audit Logs

Get audit logs for a specific organization

​
Consumption

Track detailed consumption metrics:

Consumption Cycles

View consumption cycle summaries

Daily Consumption

Get daily consumption breakdowns

By Organization

Track consumption by organization

By User

Track consumption by user

By Session

Track consumption by session

​
Organizations

Manage organizations with full RBAC:

List Organizations

View all organizations

Create Organization

Create a new organization

Update Organization

Update organization settings

Delete Organization

Delete an organization

​
Service Users

Manage service users at enterprise and organization levels:

List Enterprise Service Users

View enterprise service users

Create Enterprise Service User

Create an enterprise service user

Update Enterprise Service User

Update an enterprise service user

Delete Enterprise Service User

Delete an enterprise service user

List Org Service Users

View organization service users

Create Org Service User

Create an organization service user

​
Users

Manage users at enterprise and organization levels:

List Enterprise Users

View enterprise users

Add Enterprise User

Add a user to the enterprise

Update Enterprise User

Update an enterprise user

Remove Enterprise User

Remove a user from the enterprise

List Org Users

View organization users

Add Org User

Add a user to an organization

​
IDP Groups

Manage IdP groups at enterprise and organization levels:

List Registered Enterprise Groups

List IDP groups registered with this enterprise

Register Enterprise Groups

Register IDP groups for this enterprise

Remove Registered Enterprise Group

Remove a registered IDP group from this enterprise

List Enterprise Groups

View enterprise IdP group assignments

Assign Enterprise Group

Assign an IdP group role at the enterprise level

List Org Groups

View organization IdP group assignments

Assign Org Group

Assign an IdP group role at the organization level

​
Git Permissions

Manage repository access:

List Permissions

View git permissions for an organization

Add Permission

Add a git permission

Remove Permission

Remove a git permission

​
Notes

Manage knowledge notes at enterprise and organization levels:

List Enterprise Notes

View enterprise knowledge notes

Create Enterprise Note

Create a new enterprise note

List Org Notes

View organization knowledge notes

Create Org Note

Create a new organization note

​
Playbooks

Manage playbooks at enterprise and organization levels:

List Enterprise Playbooks

View enterprise playbooks

Create Enterprise Playbook

Create a new enterprise playbook

List Org Playbooks

View organization playbooks

Create Org Playbook

Create a new organization playbook

​
Sessions

Manage organization sessions:

List Sessions

View sessions for an organization

Create Session

Create a new session

Terminate Session

Terminate an active session

Archive Session

Archive a session for future reference

​
Tags

Manage organization tags (requires session tags feature):

Get Tags

View tags for an organization

Add Tags

Append tags to an organization

Replace Tags

Replace all tags for an organization

Delete Tag

Remove a specific tag

​
Roles & Metrics

List Roles

View available roles

Usage Metrics

Get enterprise usage metrics

Org Metrics

Get organization usage metrics

​
Usage Examples

View Code Examples

Check out code examples and common use cases for the v3 API