Skip to main content

​
Consumer Guide

If you are integrating through the Apiosk MCP package in local stdio mode, run apiosk_get_started first. It can save a dashboard connect string or create a local wallet, then verify the setup with discovery plus a first execute attempt.

​
1. Discover a listing

Start with the public catalog. 
curl "https://gateway.apiosk.com/v1/apis?search=graph&limit=5"
If you need category-level browsing, use GET /types and GET /types/:listing_type/v1.

​
2. Read agent-native metadata

The best entrypoint for agents is: 
curl https://gateway.apiosk.com/neural-sync-01/metadata
The metadata response exposes:
  • operation names
  • default operation
  • input and output schema hints
  • cost and latency metadata
  • tags and other agent-facing discovery fields

​
3. Execute using the uniform contract

For default-operation APIs, POST /execute accepts raw JSON directly. 
curl -X POST https://gateway.apiosk.com/neural-sync-01/execute \
  -H "Content-Type: application/json" \
  -H "x-payment: <x402-proof>" \
  -d '{
    "query": "What does Apiosk do?",
    "context": "Apiosk is a pay-per-call API marketplace for agents."
  }'
If you need to choose a non-default operation, use the explicit envelope: 
curl -X POST https://gateway.apiosk.com/graph-nexus-api/execute \
  -H "Content-Type: application/json" \
  -H "x-payment: <x402-proof>" \
  -d '{
    "operation": "extract",
    "input": {
      "text": "OpenAI partnered with Microsoft to scale AI infrastructure."
    }
  }'

​
4. Handle payment

Paid routes return HTTP 402 with a machine-readable requirement. Your payer signs that requirement and sends the resulting proof in the x-payment header. The gateway does not require API keys for this flow. If you are using the local MCP package, you normally do not need to build this first step by hand. apiosk_get_started configures the local payment state and tells you if the setup is ready or still needs wallet funding.

​
5. Read the normalized response

Successful execute responses are wrapped into a consistent envelope: 
{
  "status": "success",
  "result": {
    "answer": "Apiosk is a pay-per-call API marketplace for agents."
  },
  "cost": 0.015,
  "latency": 1428,
  "operation": "query",
  "api": "neural-sync-01",
  "upstream_status": 200
}
Use passthrough routes only if you deliberately want provider-specific request and response shapes. For generic agent integrations, prefer GET /metadata plus POST /execute.