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

# Agents API

> Programmatic access to Writesonic Agents: projects, tasks, playbooks, grids, knowledge, and content intelligence, over a simple API-key-authenticated REST API.

The Agents API is the REST interface to [Writesonic Agents](/agents/overview). It exposes the same capabilities as the [Agents MCP server](/agents-mcp/mcp-server): read your projects, create and manage tasks, inspect playbooks and grids, search knowledge, and pull content-intelligence reports, all as plain HTTP endpoints you can call from any language.

<Info>
  **Agents is in beta.** Access is currently limited to selected enterprise and agency accounts. To request it, talk to your account manager or [book a demo](https://writesonic.com/?demo=open) with our sales team.
</Info>

## Base URL

```
https://hq-backend-prod.writesonic.com
```

All endpoints are mounted under `/api/v1/business`. Every request is a JSON `POST` (a few reads are `GET`), and every response is JSON.

## Authentication

Every request requires your Writesonic API key in the `X-API-Key` header.

```bash theme={"system"}
curl --request GET \
  --url https://hq-backend-prod.writesonic.com/api/v1/business/whoami \
  --header 'X-API-Key: <your-api-key>'
```

### How to find your API key

<Steps>
  <Step title="Log in to Writesonic">
    Go to [app.writesonic.com](https://app.writesonic.com) and sign in.
  </Step>

  <Step title="Open the API Dashboard">
    Hover over your profile picture in the top-right corner and select **API Dashboard**.
  </Step>

  <Step title="Activate the API">
    Switch the activation toggle **on** to enable API access.
  </Step>

  <Step title="Reveal your API key">
    Click **Reveal API Key** and copy it.
  </Step>
</Steps>

<Warning>
  Never commit your API key to a public repository or ship it in client-side code. Use environment variables or a secrets manager.
</Warning>

## Scoping a request

Your API key is scoped to a single workspace. Most endpoints act on a single **project** within it, which you name with a request header.

| Header         | Value                         | Required                        |
| -------------- | ----------------------------- | ------------------------------- |
| `X-API-Key`    | Your Writesonic API key       | Always                          |
| `X-Project-Id` | The project a request targets | For project-scoped endpoints    |
| `Content-Type` | `application/json`            | For `POST` requests with a body |

<Note>
  `GET /whoami` is the one call that needs no `X-Project-Id`. Call it first, it returns your identity, your teams, and the projects in the active workspace. Use a project's `id` from that response as the `X-Project-Id` header on every other call.
</Note>

## Your first request

<Steps>
  <Step title="Get your projects">
    ```bash theme={"system"}
    curl --request GET \
      --url https://hq-backend-prod.writesonic.com/api/v1/business/whoami \
      --header 'X-API-Key: <your-api-key>'
    ```

    Copy the `id` of the project you want to work with from the `projects` array.
  </Step>

  <Step title="Query that project's tasks">
    ```bash theme={"system"}
    curl --request POST \
      --url https://hq-backend-prod.writesonic.com/api/v1/business/tasks/query \
      --header 'X-API-Key: <your-api-key>' \
      --header 'X-Project-Id: <project-id>' \
      --header 'Content-Type: application/json' \
      --data '{"view": "list"}'
    ```
  </Step>
</Steps>

## Error responses

| Status | Meaning                                                   |
| ------ | --------------------------------------------------------- |
| `401`  | Missing or invalid API key                                |
| `403`  | Key is valid but lacks access to the project or workspace |
| `422`  | Validation error in the request body or headers           |
| `429`  | Rate limit exceeded                                       |

## MCP or REST?

The Agents API and the [Agents MCP server](/agents-mcp/mcp-server) are two front doors to the same tools.

* Reach for **REST** when you're writing code, a backend job, a script, an integration.
* Reach for **MCP** when you want an AI assistant (Claude, ChatGPT) to call these tools for you in natural language.

Each REST endpoint below maps to one MCP tool of the same name, see the [tools reference](/agents-mcp/tools-reference) for the mapping.