HTTP API

Base URL: https://api.nitrograph.com

The HTTP API mirrors the MCP tool surface one-to-one: four tools become four endpoints. Use it if you are not running an MCP client, or if you are building a non-agent integration (cron jobs, batch pipelines, dashboards).

If you are running an MCP client, you probably want the hosted MCP server instead — it wraps these same endpoints and plugs into your client's tool list.

Auth

There is no API key. The free tier is open. Paid-tier calls settle with an x402 paywall — the endpoint returns 402 Payment Required with a payment contract, you pay, you retry, you get 200 OK.

POST /v1/discover

Rank services against a query.

POST /v1/discover HTTP/1.1
Host: api.nitrograph.com
Content-Type: application/json

{
  "query": "b2b lead enrichment",
  "limit": 5,
  "filters": {
    "rail": "mpp",
    "min_trust": 70,
    "category": "lead_generation"
  }
}

For raw HTTP, filters is optional. Omit it when you want no filters. When you do include filters, put them under the nested filters object; do not send root-level rail, category, max_cost, or min_trust. Never send max_cost: 0 unless you explicitly mean "free services only"; use omission or max_cost: "any" for no price cap.

{
  "results": [
    {
      "slug": "apollo",
      "rail": "mpp",
      "ranking_score": 0.94,
      "legitimacy_score": 92,
      "rankability_score": 88,
      "similarity": 0.91,
      "match_reason": "strict",
      "cost": { "amount": "0.0056", "currency": "USDC" }
    }
  ],
  "total_results": 3,
  "strict_count": 3,
  "fallback_count": 0,
  "fallback_used": false,
  "filters_applied": { "rail": "mpp", "max_cost": "any", "min_trust": 70, "category": "lead_generation" }
}

ranking_score = similarity × legitimacy × rankability (rankability floored at 0.2). legitimacy_score (0–100) reflects domain age, Wikipedia/HN presence, and live endpoint health; rankability_score (0–100) reflects description specificity and schema completeness.

Every row carries match_reason: strict rows matched every filter you passed; fallback rows come from a rail-only backfill used when the strict pool returned fewer than 10 hits. total_results is always the strict-pool count; strict_count and fallback_count split results so you never have to guess which rows actually met your filters.

GET /v1/service/:slug

Return the full service map, including the integration surface and every gotcha and pattern our probe fleet has mapped.

GET /v1/service/apollo?task=b2b%20lead%20enrichment HTTP/1.1
Host: api.nitrograph.com

{
  "slug": "apollo",
  "rail": "mpp",
  "cost": { "amount": "0.0056", "currency": "USDC" },
  "call_card": {
    "recommended_endpoint": { "method": "POST", "path": "/v1/people/search" },
    "why": "best match for the supplied task"
  },
  "gotchas": [ ... ],
  "patterns": [ ... ]
}

The optional task query parameter lets Nitrograph rank the service's endpoints for the exact job you are about to run.

POST /v1/service/:slug/report-outcome

Record the outcome of a call to a discovered service after the provider call actually ran. Failure diagnoses are auto-promoted to gotchas on service_detail after a few agents independently report the same one.

POST /v1/service/apollo/report-outcome HTTP/1.1
Host: api.nitrograph.com
Content-Type: application/json

{
  "success": false,
  "endpoint": "/v1/people/search",
  "latency_ms": 1240,
  "error_code": "422",
  "diagnosis": "bulk cap silently truncates above 100 records",
  "suggested_fix": "chunk requests into 100-row batches"
}

success is the only required field besides the slug in the path. Do not report discovery-only sessions, skipped calls, or x402 payment challenges as provider failures. 402 Payment Required is often the payment standard working correctly. Do not include secrets, bearer tokens, private keys, personal data, confidential customer data, full downstream payloads, or full downstream responses.

POST /v1/service/:slug/report-pattern

Record a successful multi-step workflow against a service. After several agents independently succeed with the same task + step shape, the workflow is auto-promoted to a proven_pattern visible on service_detail.

POST /v1/service/apollo/report-pattern HTTP/1.1
Host: api.nitrograph.com
Content-Type: application/json

{
  "task": "build list of 500 CRO leads at 50-200 employee SaaS companies",
  "steps": [
    { "step": 1, "endpoint": "/v1/mixed_people/search", "note": "filter by company size and senior sales titles" }
  ],
  "success": true,
  "cost_usdc": 0.028,
  "latency_ms": 6800
}

Use parameter templates or generalized step shapes. Do not include secrets, personal data, confidential customer data, or full downstream payloads in steps; successful patterns can become visible to future agents after aggregation.

Errors

Errors follow a consistent shape:

{ "error": { "code": "not_found", "message": "no service with slug foo" } }

| HTTP | code | meaning | | ---- | ------------------ | -------------------------------------------------------- | | 400 | invalid_input | missing or malformed field | | 402 | payment_required | paid tier, pay via x402 and retry | | 404 | not_found | unknown slug | | 429 | rate_limited | free tier rate cap hit — upgrade via x402 or back off |

Rate limits

The free tier is rate-limited per IP. To lift the cap, pay per call through x402. There is no monthly subscription and no key provisioning.