> ## Documentation Index > Fetch the complete documentation index at: https://docs.near.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create response > Generate a single-turn, stateless AI response with optional streaming. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/responses openapi: 3.1.0 info: title: NEAR AI Cloud API description: >- NEAR AI Cloud API for private AI model inference and organization administration. contact: name: NEAR AI Team email: support@near.ai license: name: MIT version: 1.0.0 servers: - url: https://cloud-api.near.ai description: NEAR AI Cloud security: - session_token: [] - api_key: [] tags: - name: Chat description: Chat completion endpoints for AI model inference - name: Images description: Image generation endpoints - name: Audio description: Audio transcription endpoints - name: Rerank description: Document reranking endpoints - name: Score description: Text similarity scoring endpoints - name: Privacy description: Privacy classification (PII span detection) endpoints - name: Models description: Public model catalog and information - name: Responses description: >- Stateless response inference (`store: false` only). Raw request/response content, response items, and history are not persisted. Clients must include any prior context in each request. Every successful Responses inference makes exactly one Chat Completions call. Only custom `function` tools are supported. They are client-managed: Cloud returns `function_call` items but never executes them; a later `store: false` request replays the individual call (the raw item from output is accepted) with its matching `function_call_output`, alongside caller-managed message history and the same function tool definitions. The minimal replay path also accepts assistant `message` text parts of type `output_text`, but not reasoning or arbitrary full `response.output` items. Server-executed tools (`web_search`, `web_context_search`, `file_search`, `code_interpreter`, `computer`, and remote `mcp`) and image-generation/editing models are rejected. The separate `POST /mcp` endpoint continues to expose its `web_search` tool independently of Responses; use `/v1/images/*` for image generation/editing. Existing completed-response gateway attestation is preserved best-effort: when the signature write succeeds, `GET /v1/signature/resp_*` retrieves signatures over SHA-256 request/response digests, never raw content. Interrupted streams create no `resp_*` attestation record or legacy disconnect fallback. Conversations, response history, and file input are rejected. - name: Organizations description: Organization management - name: Organization Members description: Organization member and invitation management - name: Workspaces description: Workspace and API key management - name: Users description: User profile and token management - name: Invitations description: Token-based invitation handling - name: Usage description: Usage tracking and billing information - name: Reporting description: Read-only customer usage reporting - name: Billing description: Billing costs endpoint (HuggingFace integration) - name: Staking Farm description: House of Stake farm credit configuration and synchronization - name: Health description: Health check endpoints - name: Attestation description: Attestation and verification endpoints - name: Gateway description: Model gateway integration endpoints - name: Admin description: Administrative endpoints (admin access required) - name: Services description: Public platform services (e.g. web_search pricing) paths: /v1/responses: post: tags: - Responses summary: Create response description: Generate a single-turn, stateless AI response with optional streaming. operationId: create_response requestBody: content: application/json: schema: $ref: '#/components/schemas/StatelessCreateResponseRequestSchema' required: true responses: '200': description: Response created content: application/json: schema: $ref: '#/components/schemas/ResponseObject' '400': description: Invalid request content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '402': description: Insufficient credits content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Server error content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - api_key: [] components: schemas: StatelessCreateResponseRequestSchema: type: object description: >- OpenAPI-only view of the stateless Responses request contract. The runtime request type keeps legacy variants so it can return a precise `invalid_request_error` for them. The public endpoint schema should instead show only the items accepted by the stateless implementation. required: - model properties: include: type: - array - 'null' items: type: string input: oneOf: - type: 'null' - $ref: '#/components/schemas/StatelessResponseInputSchema' instructions: type: - string - 'null' max_output_tokens: type: - integer - 'null' format: int64 max_tool_calls: type: - integer - 'null' format: int64 metadata: {} model: type: string parallel_tool_calls: type: - boolean - 'null' prompt_cache_key: type: - string - 'null' reasoning: oneOf: - type: 'null' - $ref: '#/components/schemas/ResponseReasoningConfig' safety_identifier: type: - string - 'null' service_tier: type: - string - 'null' store: type: boolean description: Must be `false` when supplied; omitted is normalized to `false`. default: false example: false const: false stream: type: - boolean - 'null' temperature: type: - number - 'null' format: float tool_choice: oneOf: - type: 'null' - $ref: '#/components/schemas/ResponseToolChoice' tools: type: - array - 'null' items: $ref: '#/components/schemas/StatelessResponseToolSchema' top_p: type: - number - 'null' format: float ResponseObject: type: object description: Complete response object required: - id - object - created_at - status - model - output - parallel_tool_calls - store - temperature - tool_choice - tools - top_p - usage properties: background: type: boolean conversation: oneOf: - type: 'null' - $ref: '#/components/schemas/ConversationResponseReference' created_at: type: integer format: int64 error: oneOf: - type: 'null' - $ref: '#/components/schemas/ResponseError' id: type: string incomplete_details: oneOf: - type: 'null' - $ref: '#/components/schemas/ResponseIncompleteDetails' instructions: type: - string - 'null' max_output_tokens: type: - integer - 'null' format: int64 max_tool_calls: type: - integer - 'null' format: int64 metadata: {} model: type: string next_response_ids: type: array items: type: string object: type: string output: type: array items: $ref: '#/components/schemas/ResponseOutputItem' parallel_tool_calls: type: boolean previous_response_id: type: - string - 'null' prompt_cache_key: type: - string - 'null' prompt_cache_retention: type: - string - 'null' reasoning: oneOf: - type: 'null' - $ref: '#/components/schemas/ResponseReasoningOutput' safety_identifier: type: - string - 'null' service_tier: type: string status: $ref: '#/components/schemas/ResponseStatus' store: type: boolean temperature: type: number format: float tool_choice: $ref: '#/components/schemas/ResponseToolChoiceOutput' tools: type: array items: $ref: '#/components/schemas/ClientManagedResponseTool' top_logprobs: type: integer format: int32 top_p: type: number format: float truncation: type: string usage: $ref: '#/components/schemas/Usage' user: type: - string - 'null' ErrorResponse: type: object required: - error properties: error: $ref: '#/components/schemas/ErrorDetail' StatelessResponseInputSchema: oneOf: - type: string - type: array items: $ref: '#/components/schemas/StatelessResponseInputItemSchema' ResponseReasoningConfig: type: object description: Reasoning configuration properties: effort: type: - string - 'null' ResponseToolChoice: oneOf: - type: string - type: object required: - type - function properties: function: $ref: '#/components/schemas/ResponseToolChoiceFunction' type: type: string description: Tool choice configuration StatelessResponseToolSchema: oneOf: - type: object required: - name - type properties: description: type: - string - 'null' name: type: string parameters: {} type: type: string enum: - function ConversationResponseReference: type: object description: Conversation reference in response object required: - id properties: id: type: string ResponseError: type: object required: - message - type properties: code: type: - string - 'null' message: type: string param: type: - string - 'null' type: type: string ResponseIncompleteDetails: type: object required: - reason properties: reason: type: string ResponseOutputItem: oneOf: - type: object required: - id - status - role - content - model - type properties: content: type: array items: $ref: '#/components/schemas/ResponseContentItem' created_at: type: integer format: int64 id: type: string metadata: {} model: type: string next_response_ids: type: array items: type: string previous_response_id: type: - string - 'null' response_id: type: string role: type: string status: $ref: '#/components/schemas/ResponseItemStatus' type: type: string enum: - message - type: object required: - id - status - tool_type - function - model - type properties: created_at: type: integer format: int64 function: $ref: '#/components/schemas/ResponseOutputFunction' id: type: string model: type: string next_response_ids: type: array items: type: string previous_response_id: type: - string - 'null' response_id: type: string status: $ref: '#/components/schemas/ResponseItemStatus' tool_type: type: string type: type: string enum: - tool_call - type: object required: - id - status - action - model - type properties: action: $ref: '#/components/schemas/WebSearchAction' created_at: type: integer format: int64 id: type: string model: type: string next_response_ids: type: array items: type: string previous_response_id: type: - string - 'null' response_id: type: string status: $ref: '#/components/schemas/ResponseItemStatus' type: type: string enum: - web_search_call - type: object required: - id - status - summary - content - model - type properties: content: type: string created_at: type: integer format: int64 id: type: string model: type: string next_response_ids: type: array items: type: string previous_response_id: type: - string - 'null' response_id: type: string status: $ref: '#/components/schemas/ResponseItemStatus' summary: type: string type: type: string enum: - reasoning - type: object description: >- MCP tool list - emitted after connecting to an MCP server. Clients can include this in subsequent requests to skip tool discovery. required: - id - server_label - tools - type properties: error: type: - string - 'null' description: Error message if the server could not list tools id: type: string server_label: type: string tools: type: array items: $ref: '#/components/schemas/McpDiscoveredTool' type: type: string enum: - mcp_list_tools - type: object description: MCP tool call - emitted after executing a tool on an MCP server required: - id - server_label - name - arguments - model - type properties: approval_request_id: type: - string - 'null' arguments: type: string created_at: type: integer format: int64 error: type: - string - 'null' id: type: string model: type: string name: type: string next_response_ids: type: array items: type: string output: type: - string - 'null' previous_response_id: type: - string - 'null' response_id: type: string server_label: type: string status: type: - string - 'null' description: >- Status of the tool call: in_progress, completed, incomplete, calling, or failed type: type: string enum: - mcp_call - type: object description: MCP approval request - emitted when a tool requires approval required: - id - server_label - name - arguments - model - type properties: arguments: type: string created_at: type: integer format: int64 id: type: string model: type: string name: type: string next_response_ids: type: array items: type: string previous_response_id: type: - string - 'null' response_id: type: string server_label: type: string type: type: string enum: - mcp_approval_request - type: object description: >- Function call requiring client execution Emitted when the LLM calls an external function that must be executed by the client. The client should execute the function and submit a FunctionCallOutput input. required: - id - call_id - name - arguments - status - model - type properties: arguments: type: string description: JSON-encoded arguments call_id: type: string description: The LLM's tool_call_id for correlation with FunctionCallOutput created_at: type: integer format: int64 id: type: string model: type: string name: type: string description: Function name next_response_ids: type: array items: type: string previous_response_id: type: - string - 'null' response_id: type: string status: type: string description: 'Status: "in_progress" when pending client execution' thought_signature: type: - string - 'null' description: >- Provider-specific metadata that clients must echo unchanged when replaying the function call (for example Gemini's thought signature). type: type: string enum: - function_call - type: object description: |- Result of a client-executed function call. Stored when the client submits a FunctionCallOutput input item. required: - id - call_id - output - type properties: call_id: type: string description: The call_id from the FunctionCall this is a response to created_at: type: integer format: int64 id: type: string next_response_ids: type: array items: type: string output: type: string description: Result of the function execution previous_response_id: type: - string - 'null' response_id: type: string type: type: string enum: - function_call_output description: Output item from response ResponseReasoningOutput: type: object properties: effort: type: - string - 'null' summary: type: - string - 'null' ResponseStatus: type: string enum: - completed - failed - in_progress - cancelled - queued - incomplete ResponseToolChoiceOutput: oneOf: - type: string - type: object required: - type - function properties: function: $ref: '#/components/schemas/ResponseToolChoiceFunction' type: type: string ClientManagedResponseTool: oneOf: - type: object required: - name - type properties: description: type: - string - 'null' name: type: string parameters: {} type: type: string enum: - function description: >- The only tool shape accepted from a public Responses request. `ResponseTool` retains legacy variants for dormant/internal code paths, but the `CreateResponseRequest::tools` deserializer first parses this enum. That makes unsupported builtin types ordinary request-deserialization failures, before the route or a provider can do any work. Usage: type: object required: - input_tokens - output_tokens - total_tokens properties: input_tokens: type: integer format: int32 input_tokens_details: oneOf: - type: 'null' - $ref: '#/components/schemas/InputTokensDetails' output_tokens: type: integer format: int32 output_tokens_details: oneOf: - type: 'null' - $ref: '#/components/schemas/OutputTokensDetails' total_tokens: type: integer format: int32 ErrorDetail: type: object required: - message - type properties: code: type: - string - 'null' message: type: string param: type: - string - 'null' type: type: string StatelessResponseInputItemSchema: oneOf: - type: object required: - type - call_id - name - arguments properties: arguments: type: string call_id: type: string name: type: string thought_signature: type: - string - 'null' type: $ref: '#/components/schemas/FunctionCallType' - type: object required: - type - call_id - output properties: call_id: type: string output: type: string type: $ref: '#/components/schemas/FunctionCallOutputType' - type: object required: - role - content properties: content: $ref: '#/components/schemas/StatelessResponseContentSchema' metadata: {} role: type: string ResponseToolChoiceFunction: type: object required: - name properties: name: type: string ResponseContentItem: oneOf: - type: object required: - text - type properties: text: type: string type: type: string enum: - input_text - type: object required: - image_url - type properties: detail: type: - string - 'null' image_url: $ref: '#/components/schemas/ResponseImageUrl' type: type: string enum: - input_image - type: object required: - file_id - type properties: detail: type: - string - 'null' file_id: type: string type: type: string enum: - input_file - type: object required: - text - annotations - type properties: annotations: type: array items: $ref: '#/components/schemas/TextAnnotation' logprobs: type: array items: {} text: type: string type: type: string enum: - output_text - type: object required: - tool_calls - type properties: tool_calls: type: array items: $ref: '#/components/schemas/ResponseOutputToolCall' type: type: string enum: - tool_calls - type: object required: - data - type properties: data: type: array items: $ref: '#/components/schemas/ImageOutputData' description: Image data array (matches OpenAI format) type: type: string enum: - output_image url: type: - string - 'null' description: Optional URL (future support) description: >- Unified content item that can represent both user inputs and assistant outputs This replaces ResponseOutputContent and correctly represents semantic types ResponseItemStatus: type: string enum: - completed - failed - in_progress - cancelled ResponseOutputFunction: type: object required: - name - arguments properties: arguments: type: string name: type: string WebSearchAction: oneOf: - type: object required: - query - type properties: query: type: string type: type: string enum: - search description: Web search action details McpDiscoveredTool: type: object required: - name properties: annotations: {} description: type: - string - 'null' input_schema: {} name: type: string InputTokensDetails: type: object required: - cached_tokens properties: cached_tokens: type: integer format: int64 OutputTokensDetails: type: object required: - reasoning_tokens properties: reasoning_tokens: type: integer format: int64 FunctionCallType: type: string description: Type marker for a client-replayed function call input item. enum: - function_call FunctionCallOutputType: type: string description: Type marker for function call output input enum: - function_call_output StatelessResponseContentSchema: oneOf: - type: string - type: array items: $ref: '#/components/schemas/StatelessResponseContentPartSchema' ResponseImageUrl: oneOf: - type: string - type: object required: - url properties: url: type: string TextAnnotation: oneOf: - type: object required: - start_index - end_index - title - url - type properties: end_index: type: integer minimum: 0 start_index: type: integer minimum: 0 title: type: string type: type: string enum: - url_citation url: type: string description: Annotation for output text (citations, etc.) ResponseOutputToolCall: type: object required: - id - type - function properties: function: $ref: '#/components/schemas/ResponseOutputFunction' id: type: string type: type: string ImageOutputData: type: object properties: b64_json: type: - string - 'null' revised_prompt: type: - string - 'null' url: type: - string - 'null' StatelessResponseContentPartSchema: oneOf: - type: object required: - text - type properties: text: type: string type: type: string enum: - input_text - type: object required: - text - type properties: text: type: string type: type: string enum: - output_text - type: object required: - image_url - type properties: detail: type: - string - 'null' image_url: $ref: '#/components/schemas/ResponseImageUrl' type: type: string enum: - input_image securitySchemes: session_token: type: http scheme: bearer bearerFormat: JWT description: >- JWT access token for user authentication (Authorization: Bearer ). Create via POST /users/me/access_tokens. api_key: type: http scheme: bearer bearerFormat: api_key description: 'API key for programmatic access (Authorization: Bearer sk-)' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.