> ## Documentation Index
> Fetch the complete documentation index at: https://reach-owl.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# ReachOwl API Reference: Base URL, Auth, and Conventions

> The ReachOwl API v1 base URL, authentication model, request/response conventions, pagination, and status codes used across all endpoints.

The ReachOwl API lets you automate social media outreach at scale. This page explains the base URL, how authentication works, and the conventions you will see on every endpoint so you can integrate quickly and predictably.

## Base URL

All API requests are prefixed with the following base URL:

```text theme={null}
https://reachowl.com/api/v1
```

## Authentication

Every request (except `POST /api/v1/authenticate`) must include a Bearer token in the `Authorization` header.

1. Call `POST /api/v1/authenticate` with your email and password to receive a token.
2. Include that token on every subsequent request:

```bash theme={null}
curl -H "Authorization: Bearer <your_token>" \
  "https://reachowl.com/api/v1/user"
```

Expired or invalid tokens return `401 Unauthorized`.

## Request and Response Format

* Requests that send a body must set `Content-Type: application/json`.
* The API returns JSON on success. Set `Accept: application/json` or rely on the default.
* Use `GET` for reads, `POST` for creates, `PUT`/`PATCH` for updates, and `DELETE` for removals.

## Pagination

List endpoints support pagination via query parameters:

* `page` — the page number to fetch (default: 1)
* `per_page` — items per page (default: 15)

Example:

```bash theme={null}
curl -H "Authorization: Bearer <your_token>" \
  "https://reachowl.com/api/v1/campaigns?page=2&per_page=15"
```

Pagination metadata is typically included in the response body or headers depending on the endpoint.

## Status Codes

| Code  | Meaning               | When you will see it                                       |
| ----- | --------------------- | ---------------------------------------------------------- |
| `200` | OK                    | Successful read or update                                  |
| `201` | Created               | Successful create                                          |
| `204` | No Content            | Successful delete or empty update                          |
| `400` | Bad Request           | Malformed JSON, missing required fields, or invalid values |
| `401` | Unauthorized          | Missing or invalid Bearer token                            |
| `403` | Forbidden             | Valid token but insufficient permissions                   |
| `404` | Not Found             | The requested resource does not exist                      |
| `422` | Unprocessable Entity  | Validation errors (e.g., invalid email format)             |
| `429` | Too Many Requests     | Rate limit exceeded                                        |
| `500` | Internal Server Error | Server-side issue; retry later                             |

## Design Rules

* ReachOwl does not expose `/pause`, `/resume`, `/clone`, or `/schedule` routes. Instead, you control these behaviors by setting fields in the request body when creating or updating a resource.
* To clone a campaign or post-scheduler, pass `clone_from` in the `POST` body with the ID of the source resource.
* Browsers and app-states endpoints are read-only. You cannot create or update them through the API.

## Typical Integration Flow

A common first-time flow looks like this:

1. **Authenticate** — `POST /api/v1/authenticate` to get a token.
2. **Get user** — `GET /api/v1/user` to read your profile and default `team_id`.
3. **Read app state** — `GET /api/v1/app-states` to inspect available states and settings.
4. **Create resources** — Use the token and `team_id` to create campaigns, contacts, or other resources.

<CardGroup cols={2}>
  <Card title="Authenticate" icon="key" href="/api-reference/authenticate">
    Exchange credentials for a Bearer token.
  </Card>

  <Card title="User Profile" icon="user" href="/api-reference/user">
    Fetch your profile and default team.
  </Card>

  <Card title="Campaigns" icon="megaphone" href="/api-reference/campaigns/list">
    List, create, update, and manage campaigns.
  </Card>

  <Card title="Contacts" icon="address-book" href="/api-reference/contacts/list">
    List contacts and view notes.
  </Card>
</CardGroup>