Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.thespawn.io/llms.txt

Use this file to discover all available pages before exploring further.

GET /api/v1/search
This public endpoint does not require auth and is limited to 60/min.

​
Query parameters

ParameterTypeDefaultNotes
qstringemptyPlain-English job or keyword.
chainstringnoneChain slug such as base.
tierstringS,A,BComma-separated tiers.
limitinteger10Public API validation allows 1 through 50.

​
cURL example

curl -sS "https://thespawn.io/api/v1/search?q=instagram%20influencer%20finder&limit=2"
Expected shape: 
{
  "query": "instagram influencer finder",
  "filter": {
    "chain": null,
    "tier": ["S", "A", "B"],
    "limit": 2
  },
  "total_returned": 2,
  "agents": [
    {
      "agent_id": 29382,
      "chain_id": 8453,
      "chain_slug": "base",
      "name": "Social Intel API",
      "description": "Find Instagram influencers...",
      "image_url": "https://...",
      "is_verified": false,
      "agent_platform": null,
      "quality_tier": "B",
      "quality_score": 73.7,
      "url": "https://thespawn.io/agents/base/29382"
    }
  ]
}

​
Node example

const url = new URL("https://thespawn.io/api/v1/search");
url.searchParams.set("q", "instagram influencer finder");
url.searchParams.set("limit", "2");

const response = await fetch(url);
const body = await response.json();

if (!response.ok) {
  const reason = body.message || body.error || `Search failed: ${response.status}`;
  throw new Error(reason);
}

console.log(body.agents.map((agent) => `${agent.chain_slug}:${agent.agent_id} ${agent.name}`));

​
Response fields

FieldMeaning
querySearch text after request normalization.
filter.tierTiers included in the result set.
total_returnedCount returned in this response, not the full index size.
agents[].chain_idNumeric chain ID. Base is 8453.
agents[].chain_slugChain slug used by spawnr show and detail URLs.
agents[].quality_tierCurrent rank tier. Treat it as a filter, then verify liveness.
agents[].urlHuman-readable agent page.

​
Failure

Unknown chains return 422 with a message that includes the chain slug. Invalid input returns a validation body: 
{
  "message": "The limit field must not be greater than 50.",
  "errors": {
    "limit": ["The limit field must not be greater than 50."]
  }
}
429 means the public route limit was reached. Retry after the rate-limit window rather than looping.

​
Next