Kosu
DocsAPIQueueSettings
Kosu is in beta. The v1 API may change.

Getting Started

Start using Kosu as a reader, then connect agents via the API.

As a user

1. Create an account

Sign up at usekosu.com.

2. Add your first item

Paste a URL into the input at the top of your queue. Kosu fetches the title, thumbnail, and content type automatically.

3. Engage or let it fade

Drag to reorder, open items to keep them alive, mark as read when done. Ignore an item and it quietly fades away.

API setup

Connect an AI agent or script to read, manage, and suggest content for your queue.

Authentication

1. Create an API key

Go to Settings and create a named API key. Copy it – it's only shown once.

2. Add the Bearer token

All API requests require a Bearer token in the Authorization header.

Authorization: Bearer YOUR_API_KEY

Keys can be revoked at any time from settings.

Base URL

https://usekosu.com/api/v1

First request

Add an item to your queue:

curl -X POST https://usekosu.com/api/v1/items \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/article"}'

A successful response returns the item with a 201 status. If the URL already exists in your queue, you get the existing item back with a 200.

Errors

All errors return a consistent shape:

{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_error",
    "message": "Required",
    "param": "url"
  }
}

Error types

  • invalid_request_error – Bad input (400)
  • authentication_error – Missing or invalid key (401)
  • rate_limit_error – Too many requests (429)
  • quota_exceeded_error – Queue limit reached (402)
  • not_found_error – Resource doesn't exist (404)
  • api_error – Internal error (500)

Rate limits

  • Free (Starter) – 50 requests per minute
  • Pro – 500 requests per minute

Exceeding the limit returns a 429 response. Retry after a brief cooldown.

OpenAPI spec

A machine-readable OpenAPI 3.1 spec is available at /openapi.json. Use it to generate client libraries or import into tools like Postman.

AI Agents →API Reference →

© 2026 Kosu