> ## 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 Overview

> Service-key API for ACU analytics, group management, and ACU limits on federal deployments.

<Info>
  This documentation is for the federal deployments of Devin. [Back to Devin Docs](/get-started/devin-intro)
</Info>

Federal enterprise administrators can programmatically query ACU consumption and manage [groups](/federal/groups), [model availability](/federal/model-provisioning), and [ACU limits](/federal/acu-limits) using a service-key API. A [Python SDK](/federal/api/python-sdk) wraps every endpoint described in this section.

The group management and ACU cap endpoints are only available on self-hosted, multi-tenant federal deployments. They are not exposed on commercial deployments. The analytics endpoints (`/Analytics`, `/UserPageAnalytics`, and `/CascadeAnalytics`) also check the deployment's analytics-access tier; a team without analytics access receives `permission_denied`.

***

## Base URL

All requests are JSON `POST` requests to your deployment's API server:

```
https://<your-server>/api/v1/<Method>
```

Replace `<your-server>` with the API domain of your federal deployment.

## Authentication

Every request authenticates with a **service key** included in the request body:

```json theme={null}
{
  "service_key": "your_service_key_here"
}
```

To create a service key, log in to the federal portal as a team administrator and go to **Settings → Service Keys**, then create a key with the permissions required by the endpoints you plan to call.

<Warning>Keep service keys secure. Never expose them in client-side code or commit them to repositories.</Warning>

### Required permissions

| Endpoint                                                                                                            | Required permission |
| ------------------------------------------------------------------------------------------------------------------- | ------------------- |
| [Legacy usage report](/federal/api/python-sdk#per-user-usage-report) (`/UserPageAnalytics` and `/CascadeAnalytics`) | Teams Read-Only     |
| [ACU consumption](/federal/api/acu-consumption) (`/Analytics`)                                                      | Analytics Read      |
| [List groups](/federal/api/group-management#list-groups) (`/ListGroups`)                                            | Teams Read-Only     |
| [Get group](/federal/api/group-management#get-group) (`/GetGroup`)                                                  | Teams Read-Only     |
| [Create group](/federal/api/group-management#create-group) (`/CreateGroup`)                                         | Teams Update        |
| [Update group](/federal/api/group-management#update-group) (`/UpdateGroup`)                                         | Teams Update        |
| [Delete group](/federal/api/group-management#delete-group) (`/DeleteGroup`)                                         | Teams Update        |
| [List group members](/federal/api/group-management#list-group-members) (`/ListGroupMembers`)                        | Teams Read-Only     |
| [Add group members](/federal/api/group-management#add-group-members) (`/AddGroupMembers`)                           | Teams Update        |
| [Remove group members](/federal/api/group-management#remove-group-members) (`/RemoveGroupMembers`)                  | Teams Update        |
| [Get user ACU cap](/federal/api/acu-caps#get-a-users-acu-cap) (`/GetUserAcuCap`)                                    | Teams Read-Only     |
| [Update user ACU cap](/federal/api/acu-caps#set-or-clear-a-users-acu-cap) (`/UpdateUserAcuCap`)                     | Teams Update        |

### Team-scoped and group-scoped keys

Service keys are scoped when they are created:

* **Team-scoped keys** can query team-wide data and manage every group in the team.
* **Group-scoped keys** are limited to their assigned group. They can read the group's aggregate ACU total and user rows, list and read only that group, and read or update ACU caps only for current members of that group. They cannot read team-wide totals or user rows, see other groups, or create groups.

## Pagination

List groups, list group members, and per-user ACU rows are paginated:

* `page_size` — optional; defaults to 100, maximum 1,000. Omitting it or passing `0` uses the default.
* `next_page_token` — returned when more results exist. Pass it back as `page_token` with an otherwise identical request (including the same `page_size`) to fetch the next page.

Page tokens are opaque and encrypted. They expire after 24 hours. ACU-consumption tokens are bound to the endpoint, team, scope, period, group selection, and page size. Group-list and member-list tokens are bound to the endpoint, team, scope, and page size. Changing a bound value between pages returns an `invalid_argument` error.

## Errors

Errors are returned as JSON with a code and message:

```json theme={null}
{
  "code": "permission_denied",
  "message": "service key role is missing the required permission"
}
```

| Code                  | Meaning                                                                                                                                                                     |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `unauthenticated`     | The service key is missing, invalid, or expired.                                                                                                                            |
| `permission_denied`   | The service key's role lacks the required permission.                                                                                                                       |
| `invalid_argument`    | The request is malformed — for example, an invalid period, a mixed typed and custom analytics query, an empty update, or a stale or mismatched page token.                  |
| `not_found`           | The resource does not exist, belongs to another team, or is outside the service key's scope. Cross-team and out-of-scope resources are indistinguishable from missing ones. |
| `failed_precondition` | The request is valid but cannot be completed in the current state, such as setting an ACU cap for a team that is not on ACU billing or selecting an ambiguous user email.   |
| `already_exists`      | The requested group name is already in use by the team.                                                                                                                     |
| `internal`            | The service could not complete the request.                                                                                                                                 |