# Zelf API

> Creator and content intelligence API - search content, vet creators, run AI analyses, and receive webhooks.

## Start here

- [API reference](https://developers.hellozelf.com/docs): Full endpoint reference rendered from the OpenAPI spec
- [OpenAPI spec](https://developers.hellozelf.com/openapi.yaml): Machine-readable API contract; source of truth for request/response schemas
- [Authentication](https://developers.hellozelf.com/docs#authentication): x-api-key header on every request
- [Errors](https://developers.hellozelf.com/docs#errors): Stable error codes, retry behavior, recovery steps
- [Rate limiting](https://developers.hellozelf.com/docs#rate-limiting): Quota groups and 429 handling
- [Webhooks](https://developers.hellozelf.com/docs/webhooks): Event and snapshot push payloads, signature verification, and ready-to-run receiver code
- [MCP server](https://developers.hellozelf.com/mcp): The same operations as tools, for AI agents
- [Playbook](https://developers.hellozelf.com/playbook): Worked, runnable recipes

## What the API covers

Social content and creators on TikTok, YouTube and Instagram.

- Content search and ranking over posts, captions, transcripts and AI summaries
- Aggregate statistics over any filter: post count, views, engagement, earned media value, unique creators
- Creator lookup and public metrics
- Creator vetting: AI safety and brand-fit analysis of a creator
- AI analysis: ask a question in plain words over the posts a filter matches, or over their comments
- AI brand detection: every scene in a video where a brand is identifiable, timestamped and scored
- Transcription and AI summaries of a video
- Comments, brand comparison and follower history
- Webhooks: scheduled snapshots and event pushes, HMAC-signed and retried, delivered as NDJSON

## Agent guidance

- Use the OpenAPI spec as the source of truth for request and response schemas.
- Authenticate every request with the `x-api-key` header.
- Responses are JSON wrapped in an envelope (`results`, `item_count`, `page`, `next`, `previous`); read list items from `results`.
- An object's own identifier is `id`; `*_id` fields reference other resources. To follow up on a resource, pass its `id` as the documented query param (e.g. an analysis `id` as `analysis_id`, a vetting `id` as `vetting_id`).
- Long-running work (AI analyses, creator vetting) can take an hour or more. Prefer subscribing to webhooks (`ai_analysis.completed`, `creator_vetting.completed`) instead of polling. If polling is unavoidable, space requests out - tight polling can trigger `RATE_LIMIT_EXCEEDED`.
- Confirm resource state before calling state-changing endpoints (e.g. stay under the 64 sub-brand limit before creating one).
- Do not call destructive endpoints (removing tracked/influencer accounts) unless the user explicitly requests the action.

## SDKs

Six official clients, generated from the same OpenAPI spec the reference renders. Each one holds the base URL and reads `ZELF_API_KEY` from the environment, so a snippet never writes a key down or spells out a URL.

- Python: `pip install zelf-sdk` - `from zelf import ZelfAPIClient`
- TypeScript / JavaScript: `npm install zelf-sdk`
- Go: `go get github.com/hellozelf/zelf-sdk/go`
- Rust: `cargo add zelf-sdk`
- Ruby: `gem install zelf-sdk`
- .NET / C#: `dotnet add package Zelf.Sdk`

Method names follow the operation id, spelled each language's own way: `content.list` is `client.content.list(...)` in Python, `client.content.list(...)` in TypeScript, `Content.List(...)` in Go, `client.content().list(...)` in Rust, `ContentListAsync(...)` in C#. See [Install](https://developers.hellozelf.com/docs/install) for the full list.

## MCP server

Zelf speaks the Model Context Protocol, so an AI agent can call the same operations as tools instead of writing HTTP.

- [MCP guide](https://developers.hellozelf.com/mcp): the server URL, setup steps for 16 clients, and what a connection can reach
- Transport: streamable HTTP. Auth: OAuth 2.1, approved in the browser; there is no key to paste.
- Scopes: `mcp:read` covers every read tool. `mcp:write` covers `start_ai_analysis` and `start_creator_vetting` only, and spends the brand's quota.
- Read tools: `search_content`, `content_statistics`, `search_creators`, `list_comments`, `list_ai_analyses`, `get_ai_analysis`, `list_creator_vettings`, `get_creator_vetting`, `list_webhook_subscriptions`, `list_webhook_deliveries`, `zelf_quota`, `zelf_context`
- Call `zelf_context` first: it names the brands a connection can reach and the conventions that are easy to get wrong.

## Conventions that are easy to get wrong

- Sort direction is inverted: `order_by=view_count` is most-viewed first, and a `-` prefix sorts ascending.
- Content reads cover the last 7 days unless given a window. `posted_within_days` reaches back 365; a `posted_after`/`posted_before` window may sit anywhere in history but must not span more than 366 days.
- A page holds 30 rows and `page_size` cannot exceed 30.
- Searching content needs at least one of `search`, `brand_id`, `creator_id`, `creator_username` or `external_id`.
- `search` AND-es its words. `OR`, `NOT`, quoted phrases, parentheses and `ONEAR/n` are supported.
- Ids are opaque strings: pass back exactly what was given, never build one.

## More

- [Playbook](https://developers.hellozelf.com/playbook): worked recipes, each step with runnable snippets in all six languages
- [Changelog](https://developers.hellozelf.com/changelog): every API change, newest first
- [Sitemap](https://developers.hellozelf.com/sitemap.xml)