HTTP API

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

The HTTP API covers the full platform surface - discovery, service detail, managed invocation, credits, and reporting. 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

Discovery is open - no key needed. Paid invocations authenticate with an API key (ng_live_... - let your agent pair for one, or create it at nitrograph.com/login; sent as Authorization: Bearer) and settle against prepaid credits: quoted, held, validated, refunded on failure, receipted. Legacy per-call x402 settles with an x402 paywall: the endpoint returns 402 Payment Required with a payment contract, you pay, you retry, you get 200 OK.

Endpoint index

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": "/apollo/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": "/apollo/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": "/apollo/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 are FLAT: error is a machine code string; message, when present, is human-readable. Some errors add structured fields.

{ "error": "missing_scope_token", "message": "No API key. Fastest fix: START PAIRING - ...", "pair": { "start": "POST https://api.nitrograph.com/v1/auth/device/start" } }

{ "error": "invalid_request_body", "issues": [ { "path": ["query"], "message": "Required" } ] }

{ "error": "missing_inputs", "need": ["citation"], "fields": { "citation": { "type": "string", "example": "12 CFR 1026.43" } } }

Rate limits

Free discovery is rate-limited per IP. Paid invocations run on prepaid credits with a dashboard-issued API key - no subscription; per-call x402 remains as a keyless fallback.