Method	Path	Description	Cost
GET	/get	Returns the current snapshot for a city. Query parameters and request headers are echoed back under `args` and `headers`, which makes this the cheapest way to prove that the gateway forwarded exactly what the agent sent — including the upstream credential it injected.	$1.00 default	View details
POST	/post	Takes a JSON body with nested options and a tag list, and returns it under `json` together with the headers the upstream received. Use this endpoint to check that request bodies survive the gateway hop unchanged.	$1.00 default	View details
PUT	/put	Overwrites a record wholesale. Carries a versioned API header and an optional `If-Match` precondition, so it exercises a header set that is completely different from the other two endpoints.	$1.00 default	View details

Endpoint documentation

GET/get

$1.00 default

Description

Returns the current snapshot for a city. Query parameters and request headers are echoed back under `args` and `headers`, which makes this the cheapest way to prove that the gateway forwarded exactly what the agent sent — including the upstream credential it injected.

Documentation

Look up a city snapshot

Returns the current snapshot for a city. Query parameters and request headers are echoed back under args and headers, which makes this the cheapest way to prove that the gateway forwarded exactly what the agent sent — including the upstream credential it injected.

**Operation ID:** lookupCitySnapshot
**Tags:** lookup
**Authentication:** API key in header X-Api-Key.

Parameters

| Name | In | Required | Type | Description | Example |
|---|---|---:|---|---|---|
| city | query | yes | string | City to look up, as a free-form name. | Amsterdam |
| units | query | no | string | Unit system for numeric values. | metric |
| X-Client-Id | header | yes | string | Identifier of the calling agent or app. | agent-demo-1 |
| X-Trace-Id | header | no | string (uuid) | Optional correlation id, echoed back for debugging. | 0f1d8b6c-7c2c-4a4e-9c1e-3a6f5b0d2e11 |

Responses

| Status | Description | Content types |
|---|---|---|
| 200 | The echoed request — query args, headers and resolved URL. | application/json |
| 400 | Missing or malformed query parameters. | |
| 402 | Payment required — returned by the Apiosk gateway, not the upstream. | |

Pricing

$1.00 default

Authentication

API key in header `X-Api-Key`.

Parameters

{
  "properties": {
    "city": {
      "description": "City to look up, as a free-form name.",
      "example": "Amsterdam",
      "required": true,
      "type": "string",
      "x-parameter-location": "query"
    },
    "units": {
      "default": "metric",
      "description": "Unit system for numeric values.",
      "enum": [
        "metric",
        "imperial"
      ],
      "example": "metric",
      "required": false,
      "type": "string",
      "x-parameter-location": "query"
    }
  },
  "required": [
    "city"
  ],
  "type": "object"
}

Response schema

{
  "description": "What the echo upstream mirrors back for every request.",
  "properties": {
    "args": {
      "additionalProperties": {
        "type": "string"
      },
      "description": "Query parameters as received.",
      "type": "object"
    },
    "headers": {
      "additionalProperties": {
        "type": "string"
      },
      "description": "Request headers as received, lowercased.",
      "type": "object"
    },
    "json": {
      "description": "Parsed JSON request body, when one was sent.",
      "nullable": true,
      "type": "object"
    },
    "url": {
      "description": "Fully resolved upstream URL.",
      "example": "https://postman-echo.com/get?city=Amsterdam&units=metric",
      "type": "string"
    }
  },
  "type": "object",
  "x-apiosk-content-type": "application/json",
  "x-apiosk-content-types": [
    "application/json"
  ]
}

Headers

{
  "properties": {
    "X-Client-Id": {
      "description": "Identifier of the calling agent or app.",
      "example": "agent-demo-1",
      "required": true,
      "type": "string",
      "x-parameter-location": "header"
    },
    "X-Trace-Id": {
      "description": "Optional correlation id, echoed back for debugging.",
      "example": "0f1d8b6c-7c2c-4a4e-9c1e-3a6f5b0d2e11",
      "format": "uuid",
      "required": false,
      "type": "string",
      "x-parameter-location": "header"
    }
  },
  "required": [
    "X-Client-Id"
  ],
  "type": "object"
}

Example request

{
  "X-Client-Id": "agent-demo-1",
  "X-Trace-Id": "0f1d8b6c-7c2c-4a4e-9c1e-3a6f5b0d2e11",
  "city": "Amsterdam",
  "units": "metric"
}

Example response

{
  "args": {
    "city": "Amsterdam",
    "units": "metric"
  },
  "headers": {
    "host": "postman-echo.com",
    "x-api-key": "demo-secret-123",
    "x-client-id": "agent-demo-1",
    "x-trace-id": "0f1d8b6c-7c2c-4a4e-9c1e-3a6f5b0d2e11"
  },
  "url": "https://postman-echo.com/get?city=Amsterdam&units=metric"
}

POST/post

$1.00 default

Description

Takes a JSON body with nested options and a tag list, and returns it under `json` together with the headers the upstream received. Use this endpoint to check that request bodies survive the gateway hop unchanged.

Documentation

Submit a text analysis job

Takes a JSON body with nested options and a tag list, and returns it under json together with the headers the upstream received. Use this endpoint to check that request bodies survive the gateway hop unchanged.

**Operation ID:** submitAnalysis
**Tags:** analysis
**Authentication:** API key in header X-Api-Key.

Parameters

| Name | In | Required | Type | Description | Example |
|---|---|---:|---|---|---|
| X-Client-Id | header | yes | string | Identifier of the calling agent or app. | agent-demo-1 |
| X-Idempotency-Key | header | yes | string | Replay guard — resending the same key must not create a second job. | job-2026-08-03-0001 |

Request body

The text to analyse plus the options that shape the result.

**Content types:** application/json
**Required:** yes

Responses

| Status | Description | Content types |
|---|---|---|
| 200 | The echoed job — body under json, headers under headers. | application/json |
| 422 | The body failed validation. | |

Pricing

$1.00 default

Authentication

API key in header `X-Api-Key`.

Request schema

{
  "description": "The text to analyse plus the options that shape the result.",
  "properties": {
    "options": {
      "description": "Knobs that shape the analysis.",
      "properties": {
        "includeScores": {
          "default": true,
          "example": true,
          "type": "boolean"
        },
        "language": {
          "default": "en",
          "enum": [
            "en",
            "nl",
            "de",
            "fr"
          ],
          "example": "en",
          "type": "string"
        },
        "maxTokens": {
          "default": 256,
          "example": 256,
          "maximum": 4096,
          "minimum": 1,
          "type": "integer"
        }
      },
      "type": "object"
    },
    "tags": {
      "description": "Free-form labels stored with the job.",
      "example": [
        "demo",
        "webmcp"
      ],
      "items": {
        "type": "string"
      },
      "type": "array"
    },
    "text": {
      "description": "The text to analyse.",
      "example": "Apiosk lets agents pay per request instead of holding an API key.",
      "type": "string"
    }
  },
  "required": [
    "text"
  ],
  "type": "object",
  "x-apiosk-content-type": "application/json",
  "x-apiosk-content-types": [
    "application/json"
  ],
  "x-apiosk-required": true
}

Response schema

{
  "description": "What the echo upstream mirrors back for every request.",
  "properties": {
    "args": {
      "additionalProperties": {
        "type": "string"
      },
      "description": "Query parameters as received.",
      "type": "object"
    },
    "headers": {
      "additionalProperties": {
        "type": "string"
      },
      "description": "Request headers as received, lowercased.",
      "type": "object"
    },
    "json": {
      "description": "Parsed JSON request body, when one was sent.",
      "nullable": true,
      "type": "object"
    },
    "url": {
      "description": "Fully resolved upstream URL.",
      "example": "https://postman-echo.com/get?city=Amsterdam&units=metric",
      "type": "string"
    }
  },
  "type": "object",
  "x-apiosk-content-type": "application/json",
  "x-apiosk-content-types": [
    "application/json"
  ]
}

Headers

{
  "properties": {
    "X-Client-Id": {
      "description": "Identifier of the calling agent or app.",
      "example": "agent-demo-1",
      "required": true,
      "type": "string",
      "x-parameter-location": "header"
    },
    "X-Idempotency-Key": {
      "description": "Replay guard — resending the same key must not create a second job.",
      "example": "job-2026-08-03-0001",
      "required": true,
      "type": "string",
      "x-parameter-location": "header"
    }
  },
  "required": [
    "X-Client-Id",
    "X-Idempotency-Key"
  ],
  "type": "object"
}

Example request

{
  "X-Client-Id": "agent-demo-1",
  "X-Idempotency-Key": "job-2026-08-03-0001",
  "body": {
    "options": {
      "includeScores": true,
      "language": "en",
      "maxTokens": 256
    },
    "tags": [
      "demo",
      "webmcp"
    ],
    "text": "Apiosk lets agents pay per request instead of holding an API key."
  }
}

Example response

{
  "args": {},
  "headers": {
    "content-type": "application/json",
    "x-api-key": "demo-secret-123",
    "x-client-id": "agent-demo-1",
    "x-idempotency-key": "job-2026-08-03-0001"
  },
  "json": {
    "options": {
      "includeScores": true,
      "language": "en",
      "maxTokens": 256
    },
    "tags": [
      "demo",
      "webmcp"
    ],
    "text": "Apiosk lets agents pay per request instead of holding an API key."
  },
  "url": "https://postman-echo.com/post"
}

PUT/put

$1.00 default

Description

Overwrites a record wholesale. Carries a versioned API header and an optional `If-Match` precondition, so it exercises a header set that is completely different from the other two endpoints.

Documentation

Replace a stored record

Overwrites a record wholesale. Carries a versioned API header and an optional If-Match precondition, so it exercises a header set that is completely different from the other two endpoints.

**Operation ID:** replaceRecord
**Tags:** records
**Authentication:** API key in header X-Api-Key.

Parameters

| Name | In | Required | Type | Description | Example |
|---|---|---:|---|---|---|
| dryRun | query | no | boolean | Validate the payload without persisting it. | true |
| X-Api-Version | header | yes | string | Dated contract version the caller was written against. | 2026-08-01 |
| If-Match | header | no | string | ETag of the record the caller believes it is replacing. | "a1b2c3" |

Request body

The full replacement record — partial updates are rejected.

**Content types:** application/json
**Required:** yes

Responses

| Status | Description | Content types |
|---|---|---|
| 200 | The echoed record, confirming what would have been stored. | application/json |
| 412 | The If-Match precondition failed. | |

Pricing

$1.00 default

Authentication

API key in header `X-Api-Key`.

Parameters

{
  "properties": {
    "dryRun": {
      "default": false,
      "description": "Validate the payload without persisting it.",
      "example": true,
      "required": false,
      "type": "boolean",
      "x-parameter-location": "query"
    }
  },
  "required": [],
  "type": "object"
}

Request schema

{
  "description": "The full replacement record — partial updates are rejected.",
  "properties": {
    "notify": {
      "default": false,
      "description": "Send a webhook after the replacement lands.",
      "example": false,
      "type": "boolean"
    },
    "payload": {
      "properties": {
        "label": {
          "example": "high-intent",
          "type": "string"
        },
        "score": {
          "example": 0.82,
          "format": "float",
          "maximum": 1,
          "minimum": 0,
          "type": "number"
        },
        "status": {
          "enum": [
            "active",
            "paused",
            "archived"
          ],
          "example": "active",
          "type": "string"
        }
      },
      "required": [
        "status"
      ],
      "type": "object"
    },
    "recordId": {
      "description": "Id of the record being replaced.",
      "example": "rec_7f3a91",
      "type": "string"
    }
  },
  "required": [
    "recordId",
    "payload"
  ],
  "type": "object",
  "x-apiosk-content-type": "application/json",
  "x-apiosk-content-types": [
    "application/json"
  ],
  "x-apiosk-required": true
}

Response schema

{
  "description": "What the echo upstream mirrors back for every request.",
  "properties": {
    "args": {
      "additionalProperties": {
        "type": "string"
      },
      "description": "Query parameters as received.",
      "type": "object"
    },
    "headers": {
      "additionalProperties": {
        "type": "string"
      },
      "description": "Request headers as received, lowercased.",
      "type": "object"
    },
    "json": {
      "description": "Parsed JSON request body, when one was sent.",
      "nullable": true,
      "type": "object"
    },
    "url": {
      "description": "Fully resolved upstream URL.",
      "example": "https://postman-echo.com/get?city=Amsterdam&units=metric",
      "type": "string"
    }
  },
  "type": "object",
  "x-apiosk-content-type": "application/json",
  "x-apiosk-content-types": [
    "application/json"
  ]
}

Headers

{
  "properties": {
    "If-Match": {
      "description": "ETag of the record the caller believes it is replacing.",
      "example": "\"a1b2c3\"",
      "required": false,
      "type": "string",
      "x-parameter-location": "header"
    },
    "X-Api-Version": {
      "description": "Dated contract version the caller was written against.",
      "example": "2026-08-01",
      "required": true,
      "type": "string",
      "x-parameter-location": "header"
    }
  },
  "required": [
    "X-Api-Version"
  ],
  "type": "object"
}

Example request

{
  "If-Match": "\"a1b2c3\"",
  "X-Api-Version": "2026-08-01",
  "body": {
    "notify": false,
    "payload": {
      "label": "high-intent",
      "score": 0.82,
      "status": "active"
    },
    "recordId": "rec_7f3a91"
  },
  "dryRun": true
}

Example response

{
  "args": {
    "dryRun": "true"
  },
  "headers": {
    "content-type": "application/json",
    "if-match": "\"a1b2c3\"",
    "x-api-key": "demo-secret-123",
    "x-api-version": "2026-08-01"
  },
  "json": {
    "notify": false,
    "payload": {
      "label": "high-intent",
      "score": 0.82,
      "status": "active"
    },
    "recordId": "rec_7f3a91"
  },
  "url": "https://postman-echo.com/put?dryRun=true"
}

Apiosk Echo Test API

Look up a city snapshot

Parameters

Responses

Submit a text analysis job

Parameters

Request body

Responses

Replace a stored record

Parameters

Request body

Responses