> For the complete documentation index, see [llms.txt](https://docs.groundcover.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/agent-api.md).

# Agent API

Manage Agent custom instructions, usage, budgets, and skills.

Use the Agent API to manage custom instructions, review usage, set budgets, and manage reusable skills.

Organization instructions, usage reports, and budget management require **Admin** permissions, including their read operations. Personal instructions and the caller's budget-status check do not require Admin, but they require an authenticated user's access token; service-account API keys cannot perform these personal operations. An Admin service-account API key can manage organization instructions, usage reports, and budgets.

Agent Mode must be enabled for the workspace and available on the selected backend. Include `Authorization: Bearer <YOUR_ACCESS_TOKEN>` and `X-Backend-Id: <YOUR_BACKEND_ID>` on every request. The examples below use an authenticated user's access token. Workspace-level AI enablement is managed through [Tenant Settings](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/tenant-settings-api.md#ai-settings).

## Custom instructions

**GET**, **PUT**, **DELETE** `/api/agent/instructions/personal` — Authenticated user; applies to that user's instructions.

**GET**, **PUT**, **DELETE** `/api/agent/instructions/org` — Admin required.

Personal instructions are visible and editable only to the calling user. Any Admin can read or change organization instructions, including instructions saved by another Admin.

```bash
curl --request PUT 'https://api.groundcover.com/api/agent/instructions/personal' \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --header 'X-Backend-Id: <YOUR_BACKEND_ID>' \
  --header 'Content-Type: application/json' \
  --data '{"instructions":"Use UTC timestamps and explain the evidence behind conclusions."}'
```

The `instructions` field is a string of at most 20,000 characters. Reads include the instructions and, when present, `updated_at` and `updated_by`. Delete clears the override.

## Usage and budgets

Despite the `token-budgets` path, configured limits are **monthly USD cost limits**, not token counts. All operations below require Admin except the caller's budget-status check.

| Method       | Endpoint                                   | Purpose                                           | Permissions        |
| ------------ | ------------------------------------------ | ------------------------------------------------- | ------------------ |
| GET          | `/api/agent/token-budget/status`           | Check the caller's budget status.                 | Authenticated user |
| GET          | `/api/agent/token-usage`                   | Usage per user; optional `month` query parameter. | Admin              |
| GET          | `/api/agent/token-usage/users/{user_id}`   | User usage.                                       | Admin              |
| GET          | `/api/agent/token-usage/tenant`            | Organization usage and remaining budget.          | Admin              |
| GET          | `/api/agent/token-usage/history`           | Usage history.                                    | Admin              |
| GET          | `/api/agent/token-budgets`                 | Configured budgets.                               | Admin              |
| PUT / DELETE | `/api/agent/token-budgets/default`         | Set/remove the default user limit.                | Admin              |
| PUT / DELETE | `/api/agent/token-budgets/tenant`          | Set/remove the organization limit.                | Admin              |
| PUT / DELETE | `/api/agent/token-budgets/users/{user_id}` | Set/remove a user override.                       | Admin              |

```bash
curl --request PUT 'https://api.groundcover.com/api/agent/token-budgets/default' \
  --header 'Authorization: Bearer <YOUR_ACCESS_TOKEN>' \
  --header 'X-Backend-Id: <YOUR_BACKEND_ID>' \
  --header 'Content-Type: application/json' \
  --data '{"monthly_cost_limit":25}'
```

`monthly_cost_limit` must be greater than zero. The response includes `status: "ok"` and the configured limit. Use DELETE to remove an override. Per-user budget keys use the canonical user email; URL-encode it when placing it in the path. Removing a user override lets the default user budget apply.

## Skills

Use the [Agent Skills API](https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/agent-skills-api.md) to list, create, read, update, and delete reusable skills. The guide includes authentication requirements and examples for provisioning organizational skills.

Workspace members can view and use organizational Skills created by others. Any Admin can edit or delete an organizational Skill; its creator also needs Admin permissions to change it. Personal Skills are visible, usable, and editable only by their owner.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.groundcover.com/reference/remote-access-and-apis/api-examples/agent-api.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
