Data endpoints

1. POST /v1/monid/discover — search endpoints in natural language. Free.
2. POST /v1/monid/inspect — read one endpoint’s input schema and price. Free.
3. POST /v1/monid/run — execute an endpoint. Billed. Sync providers answer inline; async providers answer 202 and you poll GET /v1/monid/runs/{job_id}.

​

Quickstart

# 1) Discover — free
curl -s https://api.aireserve.com/v1/monid/discover \
  -H "Authorization: Bearer $AIRESERVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "recent tweets about a topic", "limit": 5}'

# 2) Inspect — free; read the input schema and price
curl -s https://api.aireserve.com/v1/monid/inspect \
  -H "Authorization: Bearer $AIRESERVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"provider": "apify", "endpoint": "/apidojo/tweet-scraper"}'

# 3) Run — billed to your wallet
RUN=$(curl -s -w '\n%{http_code}' https://api.aireserve.com/v1/monid/run \
  -H "Authorization: Bearer $AIRESERVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "apify",
    "endpoint": "/apidojo/tweet-scraper",
    "input": {"searchTerms": ["AI"], "maxItems": 10}
  }')
BODY=$(echo "$RUN" | sed '$d'); CODE=$(echo "$RUN" | tail -n1)

# 4) Async providers answer 202 — poll by the AI Reserve job id
if [ "$CODE" = "202" ]; then
  JOB_ID=$(echo "$BODY" | jq -r .aireserve.job_id)
  while :; do
    BODY=$(curl -s "https://api.aireserve.com/v1/monid/runs/$JOB_ID" \
      -H "Authorization: Bearer $AIRESERVE_API_KEY")
    case "$(echo "$BODY" | jq -r .aireserve.status)" in succeeded|failed) break ;; esac
    sleep 3
  done
fi
echo "$BODY" | jq .

​

Run request

​

Run response

{
  "runId": "01HXYZ1234567890ABCDEF",
  "provider": "pdl",
  "endpoint": "/person/enrich",
  "status": "COMPLETED",
  "output": { "full_name": "…" },
  "providerResponse": { "httpStatus": 200 },
  "price": { "type": "PER_CALL", "amount": { "value": 0.003, "currency": "USD" } },
  "billedUnits": 1,
  "aireserve": {
    "job_id": "0b2f9f7e-1111-4a5b-9c3d-abcdefabcdef",
    "status": "succeeded",
    "created_at": 1789700000,
    "completed_at": 1789700001,
    "error": null
  }
}

• aireserve.job_id is the identifier you poll and the request_id of the run in your usage analytics. monid’s runId is an upstream identifier and is not accepted by GET /v1/monid/runs/{job_id}.
• HTTP status mirrors the brokered provider on sync runs. A 404 with status: "COMPLETED" and providerResponse.httpStatus: 404 means the run finished and the provider found no match — that is a result, not a gateway error, and monid does not charge for it (billedUnits: 0, and nothing is debited from your wallet). Check aireserve.status for the run lifecycle and providerResponse.httpStatus for the provider’s answer.
• 202 means the provider executes asynchronously; aireserve.status is queued or running until you poll a terminal state. Most runs complete within 1–120 seconds.

​

Billing

• Price — monid’s published price for the endpoint (PER_CALL flat, or PER_RESULT with an optional base fee), shown in every discover, inspect, and run response. There is no markup: you pay what monid charges.
• Reserve, then settle — a run reserves the endpoint’s per-call price (or base fee plus one result) against your wallet at submit and settles the actual charge from monid’s reported cost at completion. Runs the provider errored on settle at $0.
• Analytics — one usage row per run: model monid:<provider><endpoint>, provider monid, media_kind: "data", media_count = units billed. Team, user, and key attribution and spend caps apply exactly as for chat.
• Caps — runs count against your per-client rate limits, and in-flight runs are capped per organization (25 concurrent, $25 estimated in flight) to bound a runaway loop.

​

Data handling

​

Errors