# LeadArena Partner API — full docs

This file concatenates the Partner API Markdown docs for AI agents.

---

# Partner API

LeadArena Partner API for server-to-server integrations. Authenticate with an API key. All actions are scoped to the `networkId` bound to that key.

## Base URL

Use the LeadArena API host for the target environment (for example `https://api.leadarena.com`). Partner routes are under `/partner`.

## For AI agents

- Index: [/llms.txt](/llms.txt)
- Full dump: [/llms-full.txt](/llms-full.txt)

## Pages

- [Authentication](auth.md) — `x-api-key` header and network scoping
- [Errors](errors.md) — status codes and example bodies
- [Enable or disable an agent](endpoints/agent-status.md) — `POST /partner/agents/status`

## Current endpoints

| Method | Path | Description |
| --- | --- | --- |
| POST | `/partner/agents/status` | Enable or disable an agent in your network |

---

# Authentication

Partner endpoints authenticate with an API key. Do not use Cognito session tokens or OAuth.

## Header

Send the key on every request:

```http
x-api-key: pk_your_partner_key
```

Example:

```bash
curl -X POST "https://api.example.com/partner/agents/status" \
  -H "x-api-key: pk_your_partner_key" \
  -H "Content-Type: application/json" \
  -d '{"agentId":"us-east-1:11111111-1111-1111-1111-111111111111","enabled":false}'
```

## Network scoping

Each API key is bound to a single `networkId` in AWS Secrets Manager. The API:

- Rejects keys that are missing or unknown (`401`)
- Only loads agents that belong to that network (`404` if the agent is in another network)

You cannot act on agents outside your network.

## Key storage

Keys are issued by LeadArena and stored as a JSON map:

```json
{
  "partner-keys": {
    "pk_abc123": { "networkId": "NETWORK_UUID", "name": "Partner A" }
  }
}
```

Do not put API keys in client-side apps, source control, or logs.

---

# Errors

Partner API errors use standard HTTP status codes and NestJS JSON bodies.

## Status codes

| Status | When |
| --- | --- |
| 400 | Validation failed or the agent is not allowed to perform the action |
| 401 | Missing or invalid `x-api-key` |
| 404 | Agent does not exist in the partner's network |
| 500 | Pause/sync of campaigns failed after disable |

## Examples

### 401 Unauthorized

```json
{
  "statusCode": 401,
  "message": "Invalid or missing API key"
}
```

### 404 Not Found

```json
{
  "statusCode": 404,
  "message": "Agent not found"
}
```

### 400 Bad Request

```json
{
  "statusCode": 400,
  "message": ["enabled must be a boolean"],
  "error": "Bad Request"
}
```

---

# Enable or disable an agent

Enable or disable an agent in the partner's network. Disable sets `agentApproved` to `false` and pauses all currently unpaused campaigns. Enable sets `agentApproved` to `true` and does not resume campaigns.

### Request

```http
POST /partner/agents/status
```

#### Headers

| Name | Required | Description |
| --- | --- | --- |
| x-api-key | Yes | Partner API key |
| Content-Type | Yes | `application/json` |

#### Request Body

```json
{
  "agentId": "us-east-1:11111111-1111-1111-1111-111111111111",
  "enabled": false
}
```

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| agentId | string | Yes | Agent to update (`us-east-1:<uuid>`). Must belong to the API key's network. |
| enabled | boolean | Yes | `false` disables the agent. `true` enables the agent. |

### Disable (`enabled: false`)

1. Sets `agentApproved` to `false`.
2. Pauses every active, currently unpaused campaign for that agent (Postgres, Bridge spending periods, DynamoDB).
3. If the network has `requireAgentApproval`, the agent cannot create campaigns, purchase bulk leads, transfer funds, create groups, deposit, or unpause campaigns.

Campaigns stay paused after a later enable until the agent (once approved) or a manager resumes them.

### Enable (`enabled: true`)

Sets `agentApproved` to `true`. Does not change campaign pause state.

### Response

#### Success (200)

```json
{
  "agentId": "us-east-1:11111111-1111-1111-1111-111111111111",
  "networkId": "22222222-2222-2222-2222-222222222222",
  "enabled": false,
  "pausedCampaignCount": 3
}
```

| Field | Type | Description |
| --- | --- | --- |
| agentId | string | Agent that was updated (`us-east-1:<uuid>`) |
| networkId | uuid | Partner network from the API key |
| enabled | boolean | Resulting enabled state |
| pausedCampaignCount | number | Campaigns paused on disable (`0` on enable) |

#### Errors

| Status | Description |
| --- | --- |
| 400 | Body validation failed |
| 401 | Invalid or missing API key |
| 404 | Agent not in this network |
| 500 | Failed to pause campaigns in Bridge or DynamoDB |

### Example

```bash
curl -X POST "https://api.example.com/partner/agents/status" \
  -H "x-api-key: pk_your_partner_key" \
  -H "Content-Type: application/json" \
  -d '{"agentId":"us-east-1:11111111-1111-1111-1111-111111111111","enabled":false}'
```