---
title: "Create a response"
method: POST
path: "/responses"
tags: ["Response"]
---

# Create a response

`POST /responses`

## Request

- Base URL: `https://api.cloudglue.dev/v1`
- URL: `https://api.cloudglue.dev/v1/responses`
- Auth: HTTP bearer

Create a new response using the Response API. This endpoint provides an OpenAI Responses-compatible interface for chat completions with video collections.

The response can be processed synchronously (default) or asynchronously using the `background` parameter.

## Request body

- CreateResponseRequest
  - `model` string, required: The model to use for generating the response. - `nimbus-001`: Fast general question answering model. Requires `knowledge_base`. Default temperature: 0.7. - `nimbus-002-preview`: Light reasoning model capable of multi-step reasoning, cross-video synthesis, and structured entity data. Requires `knowledge_base`. Supports `entity_collections` in the knowledge base. Default temperature: 1. Metadata collections (`collection_type: 'metadata'`) and entities collections (`collection_type: 'entities'`) in the knowledge base are only supported by `nimbus-002-preview` — its agent picks the retrieval scope per search call (metadata docs and file-level entity docs at file granularity, segment-level entity docs at segment granularity); `nimbus-001` rejects both (400).
  - `input` union, required: The input for the response. Can be a simple string or an array of messages.
    - string: A simple string input (treated as a user message)
    - ResponseInputMessage[]: An array of message objects
      - `type` 'message', required: The type of the message
      - `role` 'developer' | 'user' | 'assistant', required: The role of the message sender. 'developer' maps to system instructions.
      - `content` ResponseInputContent[], required: The content of the message
        - `type` 'input_text', required: The type of content
        - `text` string, required: The text content
  - `instructions` string: System instructions to guide the model's behavior (maps to developer/system message)
  - `temperature` number: Sampling temperature for the model. Defaults to 0.7 for nimbus-001 and 1 for nimbus-002-preview.
  - `knowledge_base` union: Knowledge base configuration. Determines which content the model searches for context. Three source modes are supported: - `collections`: Search within specific collections (default, backward-compatible) - `files`: Search specific files by URL or file ID (uses default index) - `default`: Search all default-indexed files for the account
    - KnowledgeBaseCollections: Search within specific collections. This is the default source mode and is backward-compatible — the `source` field can be omitted. Since 0.7.30, `collections` itself is optional when `type` is `entity_backed_knowledge` and `entity_backed_knowledge_config.entity_collections` carries at least one collection — an entity/moments-only knowledge base answers from the structured-data tools (and moment search for moments collections) with no transcript corpus. At least one of `collections` or `entity_backed_knowledge_config.entity_collections` must be present.
      - `source` 'collections': Source mode. Can be omitted for backward compatibility (defaults to `collections`).
      - `type` 'general_question_answering' | 'entity_backed_knowledge': The type of knowledge base interaction pattern. - `general_question_answering` (default): Search-and-answer over media collections. - `entity_backed_knowledge`: Enables structured entity lookups alongside video content. Requires `entity_backed_knowledge_config` and `nimbus-002-preview` model.
      - `collections` string[]: Collection IDs to search for relevant context. Collections must be of type 'rich-transcripts', 'media-descriptions', 'metadata', or 'entities'. Metadata and entities collections require the `nimbus-002-preview` model. Optional when `type` is `entity_backed_knowledge` with at least one entity collection — omit it for an entity/moments-only knowledge base.
      - `filter` SearchFilter
        - `metadata` object[]: Filter by file metadata using JSON path expressions
          - `path` string, required: JSON path for the field to filter on
          - `operator` 'NotEqual' | 'Equal' | 'LessThan' | 'GreaterThan' | 'ContainsAny' | 'ContainsAll' | 'In' | 'Like', required: Comparison operator to apply
          - `valueText` string: Text value for scalar comparison (used with NotEqual, Equal, LessThan, GreaterThan, Like)
          - `valueTextArray` string[]: Array of values for array comparisons (used with ContainsAny, ContainsAll, In)
          - `scope` 'file' | 'segment': Specifies scope of eligible search items (file/segment) to check metadata filtering conditions
        - `video_info` object[]: Filter by video information. Use scope 'file' to filter by source video properties, or 'segment' to filter by individual segment properties (e.g. segment duration).
          - `path` 'duration_seconds' | 'has_audio', required: JSON path for the field to filter on
          - `operator` 'NotEqual' | 'Equal' | 'LessThan' | 'GreaterThan' | 'ContainsAny' | 'ContainsAll' | 'In' | 'Like', required: Comparison operator to apply
          - `valueText` string: Text value for scalar comparison (used with NotEqual, Equal, LessThan, GreaterThan, Like)
          - `valueTextArray` string[]: Array of values for array comparisons (used with ContainsAny, ContainsAll, In)
          - `scope` 'file' | 'segment': Scope of the filter. 'file' filters by source video properties, 'segment' filters by segment properties. Only duration_seconds is supported with segment scope.
        - `file` object[]: Filter by file properties
          - `path` 'bytes' | 'filename' | 'uri' | 'created_at' | 'id', required: JSON path for the field to filter on
          - `operator` 'NotEqual' | 'Equal' | 'LessThan' | 'GreaterThan' | 'ContainsAny' | 'ContainsAll' | 'In' | 'Like', required: Comparison operator to apply
          - `valueText` string: Text value for scalar comparison (used with NotEqual, Equal, LessThan, GreaterThan, Like)
          - `valueTextArray` string[]: Array of values for array comparisons (used with ContainsAny, ContainsAll, In)
        - `source_metadata` SearchFilterCriteria[]: Filter by connector-provided source metadata using JSON path expressions (file scope only). Available fields depend on the file's source. Examples: source_metadata.topic (zoom), source_metadata.host_email (zoom), source_metadata.title (gong/grain/iconik), source_metadata.participants.name (grain), source_metadata.parties.email (gong), source_metadata.tags (grain, use ContainsAny), source_metadata.meeting_platform (recall), source_metadata.name (google-drive/dropbox), source_metadata.media_type (iconik), source_metadata.iconik_metadata.<FieldName> (iconik custom metadata-view fields, e.g. source_metadata.iconik_metadata.Keywords with ContainsAny). Paths through arrays of objects match when ANY element matches. ISO datetime fields (zoom start_time, gong started, grain start_datetime, recall started_at, iconik date_created) compare as strings with LessThan/GreaterThan and represent the actual meeting date (or, for iconik, the asset creation date).
          - `path` string, required: JSON path for the field to filter on
          - `operator` 'NotEqual' | 'Equal' | 'LessThan' | 'GreaterThan' | 'ContainsAny' | 'ContainsAll' | 'In' | 'Like', required: Comparison operator to apply
          - `valueText` string: Text value for scalar comparison (used with NotEqual, Equal, LessThan, GreaterThan, Like)
          - `valueTextArray` string[]: Array of values for array comparisons (used with ContainsAny, ContainsAll, In)
      - `entity_backed_knowledge_config` EntityBackedKnowledgeConfig: Configuration for entity-backed knowledge. Required when `type` is `entity_backed_knowledge`. Contains entity collections with pre-extracted structured data and optional domain context.
        - `entity_collections` EntityCollectionConfig[], required: List of entity collections that provide pre-extracted structured data. Only supported with `nimbus-002-preview` model. Entity collections contain structured entities extracted from the same videos in the main collection (e.g., action items, speakers, topics). The model can use these for fast, structured lookups instead of searching raw content.
          - `name` string: Name for the entity collection (e.g., `action_items`, `speakers_and_roles`). Used by the model to decide which collection to query. Falls back to the collection's stored name if omitted.
          - `description` string: Human-readable description of what this entity collection contains. Helps the model decide when to use this collection. Falls back to the collection's stored description if omitted.
          - `collection_id` string, uuid, required: UUID of the entity collection. Must be an existing collection of type `entities`.
        - `description` string: General context about the videos in this collection. Helps the model understand the domain. Examples: - "Sales call recordings with enterprise prospects from Q4 2024" - "Product demo videos for the Acme Analytics platform" - "Weekly team standup recordings from the engineering org"
    - KnowledgeBaseFiles: Search specific files by URL or file ID. Files must have been described or added to a collection to be searchable.
      - `source` 'files', required: Source mode identifier.
      - `files` string[], required: File references to search. Can be file UUIDs, cloudglue URIs (`cloudglue://files/...`), data connector URLs, or HTTP URLs.
    - KnowledgeBaseDefault: Search all default-indexed files for the account. Includes any file that has been described (with `use_in_default_index: true`) or added to a collection.
      - `source` 'default', required: Source mode identifier.
  - `include` string[]: Additional data to include in the response annotations
  - `tools` ResponseToolDefinition[]: Tool definitions for function calling.
    - `type` 'function', required: The type of tool (always `function`)
    - `name` string, required: The name of the function
    - `description` string: A description of what the function does
    - `parameters` object, required: JSON Schema describing the function parameters
    - `strict` boolean: Whether to enable strict schema validation
  - `max_output_tokens` integer: Maximum number of output tokens.
  - `background` boolean: Set to true to process the response in the background. When true, the response is returned immediately with status 'in_progress'.
  - `stream` boolean: Stream response via SSE. Mutually exclusive with background.

## Response `200`

Response created successfully

- Response
  - `id` string, uuid: Unique identifier for the response
  - `object` 'response': Object type identifier
  - `status` 'in_progress' | 'completed' | 'failed' | 'cancelled': Current status of the response
  - `created_at` integer: Unix timestamp of when the response was created
  - `model` string: The model used for the response
  - `instructions` string, nullable: The system instructions used
  - `output` union[], nullable: The generated output items: assistant message(s), any echoed function_call items, and one cloudglue_query_call per read-only SQL query the agent ran over structured data. Clients should tolerate unknown output-item types.
    - union
      - ResponseOutputMessage
        - `type` 'message': The type of output
        - `role` 'assistant': The role (always assistant for outputs)
        - `content` ResponseOutputContent[]: The content items in the output
          - `type` 'output_text': The type of content
          - `text` string: The generated text
          - `annotations` ResponseAnnotation[]: Citations and references in the output
            - `type` 'cloudglue_citation', required: The type of annotation
            - `collection_id` string, uuid: The collection containing the cited content. Present when using `collections` source; omitted for `files` and `default` sources.
            - `file_id` string, uuid, required: The file containing the cited content
            - `segment_id` string, uuid: The specific segment cited. Present when a matching segment is found.
            - `start_time` number, required: Start time of the cited content in seconds
            - `end_time` number: End time of the cited segment in seconds. Present when a matching segment is found.
            - `context` string: The text context of the citation
            - `relevant_sources` string[]: Relevant source descriptions (included when 'cloudglue_citations.media_descriptions' is requested)
            - `visual_scene_description` string[]: Visual descriptions (included when 'cloudglue_citations.media_descriptions' is requested)
            - `scene_text` string[]: On-screen text (included when 'cloudglue_citations.media_descriptions' is requested)
            - `speech` string[]: Speech transcripts (included when 'cloudglue_citations.media_descriptions' is requested)
            - `audio_description` string[]: Audio descriptions (included when 'cloudglue_citations.media_descriptions' is requested)
      - ResponseFunctionCall: A function/tool call the model emitted (echoed back in output for client-executed tools).
        - `type` 'function_call': The type of output item
        - `id` string: Identifier for this output item
        - `call_id` string: Correlates the call with its function_call_output
        - `name` string: The name of the called function
        - `arguments` string: JSON-encoded arguments to the function
      - ResponseQueryCall: A read-only SQL query the nimbus-002 agent ran over the structured (extracted) data. Result rows are not included in v1.
        - `type` 'cloudglue_query_call': The type of output item
        - `id` string: Identifier for this query call (query_<toolCallId>)
        - `status` 'completed' | 'failed': Whether the query executed successfully
        - `sql` string: The SQL SELECT that was executed
        - `row_count` integer: Rows returned to the model after truncation
        - `total_rows` integer, nullable: True total when the engine saw the whole result; null when truncated
        - `truncated` boolean: Whether the result was truncated (row or byte cap) before reaching the model
        - `error` string, nullable: Error message when status is failed; null otherwise
  - `usage` ResponseUsage: Token usage statistics for the response
    - `input_tokens` integer: Number of input tokens used
    - `output_tokens` integer: Number of output tokens generated
    - `total_tokens` integer: Total tokens used
  - `error` ResponseError, nullable: Error details when the response status is 'failed'
    - `message` string: Error message
    - `type` string: Error type
    - `code` string: Error code

## Other responses

- `400`: Invalid request parameters
- `403`: Usage limit reached (monthly or daily chat completions) — `code: usage_limit_reached`
- `404`: Collection not found
- `500`: An unexpected error occurred on the server

## Changes

- **2026-10-30** `23d3f240819f`: 4 info
  - added the non-success response with the status `403`
  - added the optional property `code` to the response with the `400` status
  - added the optional property `code` to the response with the `404` status
  - added the optional property `code` to the response with the `500` status
- **2026-08-24** `ba7a6332e97a`: 1 info
  - the request property `knowledge_base/oneOf[#/components/schemas/KnowledgeBaseCollections]/collections` became optional
- **2026-08-02** `a7a390d80571`: 2 breaking, 3 warning
  - added `#/components/schemas/ResponseOutputMessage, #/components/schemas/ResponseFunctionCall, #/components/schemas/ResponseQueryCall` to the `output/items/` response property `oneOf` list for the response status `200`
  - the `output/items/` response's property type changed from `object` to no type for status `200`
  - removed the optional property `output/items/content` from the response with the `200` status
  - removed the optional property `output/items/role` from the response with the `200` status
  - …1 more
- **2026-07-22** `c02e52ec2e28`: 1 info
  - added the new optional request property `knowledge_base/oneOf[#/components/schemas/KnowledgeBaseCollections]/filter/allOf[#/components/schemas/SearchFilter]/source_metadata`
- …earlier changes not shown

[Operation history](https://skmtc.dev/cloudglue/apis/cloudglue-api/changes/responses/post.md)

---

[API](https://skmtc.dev/cloudglue/apis/cloudglue-api.md) - [All operations](https://skmtc.dev/cloudglue/apis/cloudglue-api/llms.txt) - [OpenAPI document](https://skmtc.dev/cloudglue/apis/cloudglue-api/revisions/23d3f240819f?raw)