Klint for coding agents

​

Which doc to fetch when

​

Basics

• Base URL: https://api.tryklint.ai
• Auth on every request: Authorization: Bearer <api-key> (env var KLINT_API_KEY)
• JSON bodies in, JSON out; every non-2xx is the same compact JSON problem object
• IDs are opaque, prefixed, and durable: ig_post_…, ig_account_…, ig_media_…, ig_audio_…. Handles are mutable display identity; never store them as keys.

​

Choose the operation

​

Request grammar in one look

{
  "post": {
    "query": "UGC-style grooming-product demonstrations",
    "filters": {
      "posted_at": {
        "gte": "2026-06-01T00:00:00Z"
      },
      "format": {
        "in": ["reel"]
      }
    },
    "author": {
      "filters": {
        "followers_count": {
          "gte": 5000,
          "lte": 50000
        },
        "niches": {
          "contains_any": ["pets"]
        }
      }
    }
  },
  "limit": 10
}

{
  "account": {
    "query": "sporty stay-at-home moms",
    "filters": {
      "followers_count": {
        "gte": 5000,
        "lte": 50000
      }
    },
    "posts": {
      "minimum_matching_posts": 3,
      "filters": {
        "posted_at": {
          "gte": "2026-04-01T00:00:00Z",
          "lt": "2026-07-01T00:00:00Z"
        }
      }
    }
  },
  "limit": 10
}

1. Every filter value is an operator object ({"in": [...]}, {"contains_any": [...]}, {"contains_all": [...]}, {"gte": ..., "lte": ...}) or a direct boolean. Never a bare value.
2. Singular fields (format, account_type, primary_language, id, handle, audio.id) take in. Collection fields (hashtags, caption_mentions, topics, niches, creative_formats, hook.devices, hook.modalities, commercial_contexts, publishing_languages, declared_locations) take exactly one of contains_any / contains_all. Scalars (posted_at, views, likes, comments, followers_count, engagement_rate_by_views, view_ratio_to_account_baseline) take ranges. is_verified / has_paid_partnership_label take direct booleans.
3. Fields AND together. There is no negation, no OR, no exists; the grammar is positive-only.
4. sort ({"by": ..., "order": "asc"|"desc"}) only on filters-only requests; a query owns its ordering and rejects sort.
5. In account.posts.filters, the complete predicate must hold on one single post; minimum_matching_posts (1–3) counts distinct posts that each satisfy all of it.
6. Hashtags without #, handles without @ (Klint tolerates and strips leading symbols). Classification values are exact catalog IDs; Klint rejects unknown IDs with candidates, never silently empty.
7. Limits (provisional): 100 values per membership array, 20 filter fields per request, 2,000-char query, limit ≤ 100.

​

Responses

• Search envelope: { "request_id", "data": [...], "has_more", "next_cursor" }. GETs return the bare resource.
• data items are complete fixed-shape resources: post summaries or accounts. null = can’t currently support the value; [] = affirmatively empty. Never treat null as 0 or false.
• Continue a result set by POSTing { "cursor": "...", "limit": <same-or-lower> } to the same route, nothing else in the body. Cursors expire (~15–30 min) → 410 expired-cursor → run a new search.
• An empty data means no qualifying match in what Klint has observed, never proof the content doesn’t exist on Instagram. Same for 404 not-tracked on GETs.

​

Recommended defaults

• Start with limit: 10; paginate only when the task actually consumes more.
• Put hard constraints (dates, counts, formats, languages, locations) in filters; keep the query for meaning. Describe content, not keywords: “UGC-style grooming-product demonstrations”, not “dog grooming viral”.
• For discovery-then-qualification workflows: posts search first, collect distinct author.ids, then account GETs, not the other way around.
• Full posts (GET /posts/{id}) are large; fetch them only when you need media, transcript, or on-screen text. The search summary already carries interpretation and metrics.

​

Errors

​

Common mistakes

​

Availability caveat