Introduction

Base URL

The Kavio API is available at:

https://app.getkavio.app/api

Authentication

All API requests require a Bearer token in the Authorization header. You can create API keys (Personal Access Tokens) from the Kavio dashboard or via the POST /api-keys endpoint.

Authorization: Bearer YOUR_API_KEY

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.

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.

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
`404`	Resource not found, or resource not in the key’s workspace
`422`	Validation error
`429`	Rate limit exceeded

{
  "message": "The name field is required."
}

Response shape

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

{
  "id": "9f1a2b3c-...",
  "name": "...",
  "...": "..."
}

A non-paginated collection looks like a plain array:

[
  { "id": "9f1a2b3c-...", "name": "..." },
  { "id": "a1b2c3d4-...", "name": "..." }
]

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

Pagination

The GET /posts endpoint returns 15 posts per page. The response uses Laravel’s standard pagination envelope:

{
  "data": [...],
  "links": {
    "first": "https://app.getkavio.app/api/posts?page=1",
    "last":  "https://app.getkavio.app/api/posts?page=5",
    "prev":  null,
    "next":  "https://app.getkavio.app/api/posts?page=2"
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "to": 15,
    "last_page": 5,
    "per_page": 15,
    "total": 72,
    "path": "https://app.getkavio.app/api/posts",
    "links": [
      { "url": null, "label": "&laquo; Previous", "page": null, "active": false },
      { "url": "https://app.getkavio.app/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}`

Overview

Posts

Platforms

Workspace

Signatures

Labels

Social Accounts

API Keys

Base URL

Authentication

Workspace scoping

Rate limiting

Errors

Response shape

Quick reference

​Base URL

​Authentication

​Workspace scoping

​Rate limiting

​Errors

​Response shape

​Pagination

​Quick reference

Base URL

Authentication

Workspace scoping

Rate limiting

Errors

Response shape

Pagination

Quick reference