Build with Pellumin.

Quick start

Three steps to your first request.

1. Create a workspace. Sign up at /signup. We seed every new account with 1,000 free credits every month — no card required.
2. Generate an API key. In your dashboard, go to API keys → Create key. The secret is shown once — copy it immediately.
3. Make your first call.

curl 'https://api.pellumin.com/api/summary?q=how%20does%20TLS%201.3%20work' \
  -H "Authorization: Bearer plm_your_key_here"

That's it. Try it now in the Playground — every endpoint is wired and ready.

Authentication

Every request must include your API key in the Authorization header.

Authorization: Bearer plm_your_key_here

Treat the key like a password — anyone with it can spend your credits. If a key leaks, revoke it from API keys and create a new one.

Which endpoint should I use?

We expose five endpoints across two flavours: synthesis (we read the web for you and return a cited answer) and retrieval (you get the raw material and decide what to do with it).

Smart Search

A direct, cited answer to any question — synthesized from the live web in a single call.

Parameters

Example response

{
  "query": "how does TLS 1.3 handshake work",
  "answer": "TLS 1.3 reduces the handshake to a single round trip [1]. The client sends its key share in the first message, allowing the server to derive shared secrets and begin encrypting data immediately [2]...",
  "follow_up_questions": null,
  "images": [],
  "results": [
    {
      "url": "https://datatracker.ietf.org/doc/html/rfc8446",
      "title": "RFC 8446 — TLS 1.3",
      "content": "The Transport Layer Security (TLS) protocol provides...",
      "score": 0.94,
      "raw_content": null,
      "favicon": "https://www.google.com/s2/favicons?domain=datatracker.ietf.org&sz=64"
    }
  ],
  "response_time": 1.42,
  "request_id": "eede70ba-9e26-4b00-8d6f-f04ac23c0fbe"
}

The answer contains inline citations like [1], [2] referring to the index of each entry in results.

Deep Search

Multi-step research: plans sub-questions, runs parallel searches, ranks sources, extracts clean content, and synthesizes a structured cited report.

Parameters

Example response

{
  "query": "impact of AI on grid power demand",
  "answer": "## Executive summary\n\nGlobal data-centre electricity use is rising fast...\n\n## Key drivers\n- Training runs at scale [1]\n- Inference demand [2]\n...",
  "follow_up_questions": [
    "current global data-centre electricity consumption",
    "projected AI workload electricity demand 2025–2030",
    "grid upgrade investments by hyperscalers",
    "regulatory responses to data-centre power use"
  ],
  "images": [],
  "results": [ /* ranked sources */ ],
  "response_time": 18.2,
  "request_id": "..."
}

The shape is identical to Smart Search, with two differences: answer is a longer-form Markdown report (with ## headings and bullets), and follow_up_questions contains the sub-questions the agent explored.

Search

Ranked web results — title, URL, snippet. No synthesis. Use when your agent wants to pick sources itself.

Parameters

Sample response (advanced)

{
  "query": "kubernetes pod scheduling",
  "page": 1,
  "category": "general",
  "source": "websearch",
  "results": [
    {
      "title": "Pod Scheduling — Kubernetes Documentation",
      "url": "https://kubernetes.io/docs/concepts/...",
      "snippet": "...",
      "engine": null,
      "score": 0.94
    }
  ]
}

Extract

Fetch any URL and return clean Markdown, text, or a structured outline — boilerplate stripped.

Parameters

Crawl

BFS-crawl a single domain, respecting robots.txt. Returns extracted content for every page visited.

Parameters

Response shape

Both endpoints return identical JSON. Your agent can treat them interchangeably — pick the depth you need.

Result object

Errors

Errors come back as JSON with an HTTP status that matches.

A 402 response includes the required and current balance so your agent can decide whether to upgrade, top up, or surface the limit to the user.

{
  "detail": {
    "error": "insufficient_credits",
    "balance": 4,
    "required": 10,
    "message": "You need 10 credit(s) for this request but have only 4."
  }
}

Rate limits

Limits scale with your plan. The defaults:

• Up to 10 concurrent requests per workspace.
• Sustained throughput depends on plan. Hitting the limit returns 429 with a Retry-After header.
• Identical queries within 24 hours are served from cache — near-instant, still charged.

Need higher limits? Talk to us about Enterprise.

FAQ