# Hoko API

Use the Hoko API to create and update links, organize campaign metadata, read click analytics, manage workspace resources, and record lead or sale conversions.

## Authentication

Send one authorized credential. Use `Authorization: Bearer <TOKEN>` for a human token, OAuth access token, or API key. API keys may also use `X-API-Key: <API_KEY>`. First-party browser clients may use the authenticated session cookie. Every credential still needs the scope required by the operation.
Authenticated responses include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, and `X-RateLimit-Reset`. A `429` response includes `retryAfter` when the retry delay is known.

## Machine-Readable Resources

- OpenAPI: https://api.hoko.to/openapi.json
- MCP endpoint: https://mcp.hoko.to/
- Full API context: https://api.hoko.to/llms-full.txt
- API reference docs: https://docs.hoko.to/llms.txt

## Endpoint Inventory

| Method | Path | Scope | Purpose |
| --- | --- | --- | --- |
| GET | /links | linksRead | List links by id, externalId, tenantId, partnerId, and pagination parameters. |
| POST | /links | linksWrite | Create one or more short links. |
| PUT | /links | linksWrite | Create or update links; entries with id update, entries without id insert. |
| DELETE | /links | linksWrite | Soft-delete one or more links by ID. |
| GET | /collections | collectionsRead | List collections by id with pagination. |
| POST/PUT/DELETE | /collections | collectionsWrite | Create, upsert, or soft-delete collections. |
| GET | /tags | tagsRead | List tags by id with pagination. |
| POST/PUT/DELETE | /tags | tagsWrite | Create, upsert, or delete tags. |
| GET | /partners | partnersRead | List partners by id with pagination. |
| POST/PUT/DELETE | /partners | partnersWrite | Create, upsert, or soft-delete partners. |
| GET | /customers | customersRead | List customers by id or externalId with pagination. |
| PUT/DELETE | /customers | customersWrite | Update existing customers by id or externalId, or soft-delete customers by id. |
| GET | /analytics | analyticsRead | List click analytics by linkId, partnerId, startDate, endDate, and pagination parameters. |
| POST | /track/lead | conversionsWrite | Record a lead conversion and upsert the customer. |
| POST | /track/sale | conversionsWrite | Record a sale conversion and upsert the customer. |