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

# Introduction

> The TryPost API lets you manage social media posts, signatures, labels, and more with a simple REST API.

## Base URL

The TryPost API is available at:

```
https://app.trypost.it/api
```

For self-hosted instances, the base URL is your `APP_URL` followed by `/api` (e.g., `https://trypost.yourdomain.com/api`).

## Authentication

All API requests require a Bearer token in the `Authorization` header. You can create API keys (Personal Access Tokens) from the [TryPost dashboard](https://app.trypost.it/settings/authentication) or via the [`POST /api-keys`](/api-reference/endpoint/create-api-key) endpoint.

```bash theme={null}
Authorization: Bearer YOUR_API_KEY
```

<Warning>
  Keep your API key secret. Do not expose it in client-side code or public repositories. The plain token value is only shown once at creation — store it immediately.
</Warning>

## Workspace scoping

Every API key is bound to a specific workspace at creation time. All requests act on that workspace — you cannot list or modify resources from other workspaces with the same key. To work with multiple workspaces, create one API key per workspace.

The same key works for the REST API and the [MCP server](/ai/introduction).

## Rate limiting

API requests are throttled to prevent abuse. When you exceed the limit, the API returns a `429` status code with a `Retry-After` header indicating how many seconds to wait.

## Errors

The API uses conventional HTTP status codes. All error responses include a `message` field.

| Status | Description                                                                       |
| ------ | --------------------------------------------------------------------------------- |
| `200`  | Success                                                                           |
| `201`  | Created                                                                           |
| `204`  | No content (successful deletion)                                                  |
| `401`  | Missing or invalid API key                                                        |
| `402`  | Active subscription required (Cloud only — self-hosted instances skip this check) |
| `404`  | Resource not found, or resource not in the key's workspace                        |
| `422`  | Validation error                                                                  |
| `429`  | Rate limit exceeded                                                               |

```json theme={null}
{
  "message": "The name field is required."
}
```

## Response shape

Resources are returned **unwrapped** — no `data:` envelope. A single resource looks like:

```json theme={null}
{
  "id": "9f1a2b3c-...",
  "name": "...",
  "...": "..."
}
```

A non-paginated collection looks like a plain array:

```json theme={null}
[
  { "id": "9f1a2b3c-...", "name": "..." },
  { "id": "a1b2c3d4-...", "name": "..." }
]
```

The only endpoint that wraps in `data:` is `GET /posts`, because it's paginated.

## Pagination

The [`GET /posts`](/api-reference/endpoint/list-posts) endpoint returns 15 posts per page. The response uses Laravel's standard pagination envelope:

```json theme={null}
{
  "data": [...],
  "links": {
    "first": "https://app.trypost.it/api/posts?page=1",
    "last":  "https://app.trypost.it/api/posts?page=5",
    "prev":  null,
    "next":  "https://app.trypost.it/api/posts?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "to": 15,
    "last_page": 5,
    "per_page": 15,
    "total": 72,
    "path": "https://app.trypost.it/api/posts",
    "links": [
      { "url": null, "label": "&laquo; Previous", "page": null, "active": false },
      { "url": "https://app.trypost.it/api/posts?page=1", "label": "1", "page": 1, "active": true },
      { "url": null, "label": "Next &raquo;", "page": null, "active": false }
    ]
  }
}
```

Use the `page` query parameter to navigate. Other list endpoints (signatures, labels, social accounts, API keys) return all items without pagination, as a plain array.

## Quick reference

| Resource        | Endpoints                                                                                                                                                                                                  |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Posts           | `GET /posts`, `POST /posts`, `GET /posts/{id}`, `PUT /posts/{id}`, `DELETE /posts/{id}`, `POST /posts/{id}/media`, `POST /posts/{id}/media/from-url`, `GET /posts/{id}/metrics`, `GET /posts/{id}/preview` |
| Platforms       | `GET /content-types`                                                                                                                                                                                       |
| Workspace       | `GET /workspace`                                                                                                                                                                                           |
| Signatures      | `GET /signatures`, `POST /signatures`, `PUT /signatures/{id}`, `DELETE /signatures/{id}`                                                                                                                   |
| Labels          | `GET /labels`, `POST /labels`, `PUT /labels/{id}`, `DELETE /labels/{id}`                                                                                                                                   |
| Social accounts | `GET /social-accounts`, `PUT /social-accounts/{id}/toggle`                                                                                                                                                 |
| API keys        | `GET /api-keys`, `POST /api-keys`, `DELETE /api-keys/{id}`                                                                                                                                                 |