For coding agents

If you are pointing an agent at herascrape, you do not need it to crawl these pages.

Machine-readable docs

llms-full.txt is the one to hand an agent: one fetch, the whole documentation. The OpenAPI (Swagger) schema describes the paths, parameters and auth, and is emitted by the running service, so it cannot drift from what is actually served.

Response bodies are deliberately untyped

The schema declares every successful response as a bare object. That is a choice, not an omission.

We hand Instagram's payloads back with as little reshaping as we can manage, because reshaping is where a scraping API silently lies to you: a field we renamed or flattened is a field we have to keep renaming correctly forever, and the day Instagram changes it you get our stale guess instead of their data. The shape is theirs, so it is not ours to freeze in a schema.

Publishing a handful of real models beside thirty-odd untyped ones was worse than publishing none: it implied a guarantee for those few and made codegen look viable when it is not. Generate a client for the paths from this schema if it helps, but treat every response body as JSON and read the field documentation on each endpoint page for what is actually in it.

Migrating an existing client

If the codebase already talks to HikerAPI, the migration guide ends with a prompt written to be pasted into an agent. It points the agent at llms-full.txt, so it pulls these docs itself, and it handles the base URL, the header rename, the path translation and the pagination rewrite.

Writing a client from scratch

The shortest correct brief:

Write a client for the herascrape Instagram API.

- Base URL https://api.herascrape.com, auth via the `X-Api-Key` header.
- Every endpoint is a GET.
- List endpoints return {items, next_cursor, has_more}. Page by passing
  next_cursor back as ?cursor= and looping while has_more is true. Treat the
  cursor as opaque: never parse or construct one.
- Two endpoints page differently: /posts/{id}/comments uses `min_id` (read
  `next_min_id`, branch on `has_more`), and /users/{id}/posts pages on
  `cursor` taken from `feed.profile_grid_items_cursor`.
- Object responses are Instagram's raw JSON. Do not define response types;
  return parsed JSON.
- Retry 502 and 503 with backoff. Do not retry 4xx. Only 2xx responses are
  billed.
- Users are addressed by numeric id. Resolve a username once via
  GET /users/username/{username}, cache the `pk`, and use the id after that.

Full documentation: https://herascrape.com/docs/llms-full.txt
Full schema:        https://api.herascrape.com/openapi.json

Give the agent llms-full.txt alongside that brief and it has everything: every endpoint, the pagination and error contracts, and a real example response for each.

Rate limits an agent should respect

10 requests per second per key. An agent doing a bulk crawl should serialise its paging loop rather than fanning out — one Instagram page per call means concurrency buys less than it costs in 429s.

The three links again

• https://herascrape.com/docs/llms.txt — index of every page
• https://herascrape.com/docs/llms-full.txt — the whole docs, one file
• https://api.herascrape.com/openapi.json — OpenAPI (Swagger) schema