---
title: "Create a response (ZeroClick-authenticated)"
method: POST
path: "/zeroclick/v1/responses"
tags: ["ZeroClick"]
---

# Create a response (ZeroClick-authenticated)

`POST /zeroclick/v1/responses`

OpenAI-style Responses endpoint, authenticated by verifying the
`zc-signature` HMAC over the raw request bytes. The request is routed by
`model` using model metadata, and the same orchestration as
`/v1/responses` runs behind it.

On success, actual token usage is settled with ZeroClick and reported
via the `zc-usage` response header.

## Headers

- `zc-request-id` string
- `zc-agent-id` string

## Request body

- ResponsesRequest
  - `model` string, required
  - `input` string, required — Prompt text. Combined with `instructions` (as a system message) to form the model input.
  - `instructions` string — System-style instructions prepended to the input. Classification models may pass comma-separated or bracketed candidate labels here.
  - `max_output_tokens` integer, nullable
  - `parallel_tool_calls` boolean
  - `previous_response_id` string, nullable
  - `store` boolean
  - `temperature` number, nullable
  - `top_p` number, nullable
  - `truncation` 'auto' | 'disabled'
  - `categories` string[] — Candidate labels for text-classification models.
  - `multilingual` boolean
  - `metadata` object — Up to 16 string key/value pairs echoed back in the response envelope. Also carries GLiNER usecase options (`usecase`, `schema`, `labels`, `threshold`, `mask`, `replacement_char`), which are consumed and not necessarily echoed.
  - `text` object
    - `format` object
      - `type` 'text' — Output format. `text` is supported; `json` is currently rejected.

## Response `200`

OpenAI Responses `response` object. Includes the `zc-usage` header settling actual usage with ZeroClick.

- ResponsesResponse — OpenAI Responses `response` object. On error, `status` is `failed` and `error` is populated.
  - `id` string
  - `object` 'response'
  - `created_at` integer
  - `status` 'completed' | 'failed'
  - `completed_at` integer, nullable
  - `error` ResponsesError — Error attached to a Responses envelope. OpenAI's ResponseError carries `code` and `message`; `type` and `param` are also emitted by some error sites on this endpoint.
    - `type` string
    - `message` string, required
    - `param` string
    - `code` string
  - `incomplete_details` unknown
  - `instructions` string, nullable
  - `max_output_tokens` integer, nullable
  - `model` string
  - `output` object[]
    - `type` 'message'
    - `id` string
    - `status` string
    - `role` 'assistant'
    - `content` object[]
      - `type` 'output_text'
      - `text` string
      - `annotations` unknown[]
        - unknown
  - `parallel_tool_calls` boolean
  - `previous_response_id` string, nullable
  - `reasoning` object
    - `effort` unknown
    - `summary` unknown
  - `store` boolean
  - `temperature` number, nullable
  - `text` object
    - `format` object
      - `type` string
  - `tool_choice` string
  - `tools` unknown[]
    - unknown
  - `top_p` number, nullable
  - `truncation` 'auto' | 'disabled'
  - `usage` ResponsesUsage, nullable
    - `input_tokens` integer
    - `input_tokens_details` object
      - `cached_tokens` integer
    - `output_tokens` integer
    - `output_tokens_details` object
      - `reasoning_tokens` integer
    - `total_tokens` integer
  - `user` string, nullable
  - `metadata` object

## Other responses

- `400` — Invalid request — malformed JSON, or a missing/invalid required field such as `model` or `input`. Errors use the Responses error envelope.
- `401` — The `zc-signature` was missing or invalid, or ZeroClick is not configured for this environment. Unsigned/unverifiable traffic is treated as unauthenticated.
- `402` — The ZeroClick allowance check denied the request (e.g. insufficient allowance or a stale signature timestamp). Body follows ZeroClick's `payment_required` schema as returned by the SDK.
- `420` — Input token count exceeds the resolved model's `max_tokens` and the model is configured to error rather than truncate. Returned in the Responses error envelope.
- `500` — Unexpected server error.

---

[API](https://skmtc.dev/zerogpu/apis/zerogpu-batch-files-api.md) · [All operations](https://skmtc.dev/zerogpu/apis/zerogpu-batch-files-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/zerogpu/zerogpu-batch-files-api/revisions/f7371035d1a2/schema)