> ## Documentation Index > Fetch the complete documentation index at: https://docs.cloudglue.dev/llms.txt > Use this file to discover all available pages before exploring further. # Create Response > 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. ## OpenAPI ````yaml POST /responses openapi: 3.0.0 info: title: Cloudglue API description: API for Cloudglue license: name: Apache License 2.0 url: https://www.apache.org/licenses/LICENSE-2.0 version: 0.7.13 servers: - url: https://api.cloudglue.dev/v1 security: - bearerAuth: [] paths: /responses: post: tags: - Response summary: Create a response description: >- 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. operationId: createResponse requestBody: description: Response creation parameters content: application/json: schema: $ref: '#/components/schemas/CreateResponseRequest' required: true responses: '200': description: Response created successfully content: application/json: schema: $ref: '#/components/schemas/Response' '400': description: Invalid request parameters content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Collection not found content: application/json: schema: $ref: '#/components/schemas/Error' '500': description: An unexpected error occurred on the server content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: CreateResponseRequest: type: object required: - model - input properties: model: type: string minLength: 1 example: nimbus-001 description: >- 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'`) in the knowledge base are only supported by `nimbus-002-preview` — its agent retrieves them at file granularity; `nimbus-001` rejects them (400). input: oneOf: - type: string description: A simple string input (treated as a user message) - type: array description: An array of message objects items: $ref: '#/components/schemas/ResponseInputMessage' description: >- The input for the response. Can be a simple string or an array of messages. instructions: type: string description: >- System instructions to guide the model's behavior (maps to developer/system message) temperature: type: number minimum: 0 maximum: 2 description: >- Sampling temperature for the model. Defaults to 0.7 for nimbus-001 and 1 for nimbus-002-preview. knowledge_base: $ref: '#/components/schemas/ResponseKnowledgeBase' description: >- Knowledge base configuration. Required for `nimbus-001` and `nimbus-002-preview`. include: type: array items: type: string enum: - cloudglue_citations.media_descriptions description: Additional data to include in the response annotations tools: type: array description: Tool definitions for function calling. items: $ref: '#/components/schemas/ResponseToolDefinition' max_output_tokens: type: integer minimum: 1 maximum: 128000 description: Maximum number of output tokens. background: type: boolean description: >- Set to true to process the response in the background. When true, the response is returned immediately with status 'in_progress'. stream: type: boolean description: Stream response via SSE. Mutually exclusive with background. Response: type: object properties: id: type: string format: uuid description: Unique identifier for the response object: type: string enum: - response description: Object type identifier status: type: string enum: - in_progress - completed - failed - cancelled description: Current status of the response created_at: type: integer description: Unix timestamp of when the response was created model: type: string description: The model used for the response instructions: type: string nullable: true description: The system instructions used output: type: array nullable: true items: $ref: '#/components/schemas/ResponseOutputMessage' description: The generated output messages usage: $ref: '#/components/schemas/ResponseUsage' nullable: true error: $ref: '#/components/schemas/ResponseError' nullable: true Error: required: - error type: object properties: error: type: string ResponseInputMessage: type: object required: - type - role - content properties: type: type: string enum: - message description: The type of the message role: type: string enum: - developer - user - assistant description: >- The role of the message sender. 'developer' maps to system instructions. content: type: array items: $ref: '#/components/schemas/ResponseInputContent' description: The content of the message ResponseKnowledgeBase: description: >- 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 oneOf: - $ref: '#/components/schemas/KnowledgeBaseCollections' - $ref: '#/components/schemas/KnowledgeBaseFiles' - $ref: '#/components/schemas/KnowledgeBaseDefault' discriminator: propertyName: source mapping: collections: $ref: '#/components/schemas/KnowledgeBaseCollections' files: $ref: '#/components/schemas/KnowledgeBaseFiles' default: $ref: '#/components/schemas/KnowledgeBaseDefault' ResponseToolDefinition: type: object description: Tool definition for function calling. required: - type - name - parameters properties: type: type: string enum: - function description: The type of tool (always `function`) name: type: string minLength: 1 description: The name of the function description: type: string description: A description of what the function does parameters: type: object description: JSON Schema describing the function parameters additionalProperties: true strict: type: boolean description: Whether to enable strict schema validation ResponseOutputMessage: type: object properties: type: type: string enum: - message description: The type of output role: type: string enum: - assistant description: The role (always assistant for outputs) content: type: array items: $ref: '#/components/schemas/ResponseOutputContent' description: The content items in the output ResponseUsage: type: object description: Token usage statistics for the response properties: input_tokens: type: integer description: Number of input tokens used output_tokens: type: integer description: Number of output tokens generated total_tokens: type: integer description: Total tokens used ResponseError: type: object description: Error details when the response status is 'failed' nullable: true properties: message: type: string description: Error message type: type: string description: Error type code: type: string description: Error code ResponseInputContent: type: object required: - type - text properties: type: type: string enum: - input_text description: The type of content text: type: string description: The text content KnowledgeBaseCollections: type: object description: >- Search within specific collections. This is the default source mode and is backward-compatible — the `source` field can be omitted. required: - collections properties: source: type: string enum: - collections description: >- Source mode. Can be omitted for backward compatibility (defaults to `collections`). type: type: string enum: - general_question_answering - entity_backed_knowledge description: >- 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: type: array items: type: string format: uuid minItems: 1 description: Collection IDs to search for relevant context filter: description: >- Optional filter to narrow down the search within collections. Supports filtering by `metadata`, `video_info`, and `file` properties. Each filter is an array of criteria with `path`, `operator`, and `valueText` or `valueTextArray`. Supported operators: `Equal`, `NotEqual`, `LessThan`, `GreaterThan`, `In`, `ContainsAny`, `ContainsAll`. Examples: - Filter by file ID: `{"file": [{"path": "id", "operator": "Equal", "valueText": "file-uuid"}]}` - Filter by metadata: `{"metadata": [{"path": "speaker", "operator": "Equal", "valueText": "Amy"}]}` - Filter by duration: `{"video_info": [{"path": "duration_seconds", "operator": "GreaterThan", "valueText": "60"}]}` allOf: - $ref: '#/components/schemas/SearchFilter' entity_backed_knowledge_config: $ref: '#/components/schemas/EntityBackedKnowledgeConfig' KnowledgeBaseFiles: type: object description: >- Search specific files by URL or file ID. Files must have been described or added to a collection to be searchable. required: - source - files properties: source: type: string enum: - files description: Source mode identifier. files: type: array items: type: string minItems: 1 description: >- File references to search. Can be file UUIDs, cloudglue URIs (`cloudglue://files/...`), data connector URLs, or HTTP URLs. KnowledgeBaseDefault: type: object description: >- 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. required: - source properties: source: type: string enum: - default description: Source mode identifier. ResponseOutputContent: type: object properties: type: type: string enum: - output_text description: The type of content text: type: string description: The generated text annotations: type: array items: $ref: '#/components/schemas/ResponseAnnotation' description: Citations and references in the output SearchFilter: type: object properties: metadata: type: array description: Filter by file metadata using JSON path expressions items: allOf: - $ref: '#/components/schemas/SearchFilterCriteria' - type: object properties: scope: type: string enum: - file - segment description: >- Specifies scope of eligible search items (file/segment) to check metadata filtering conditions video_info: type: array description: >- 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). items: allOf: - $ref: '#/components/schemas/SearchFilterCriteria' - type: object properties: path: type: string enum: - duration_seconds - has_audio scope: type: string enum: - file - segment description: >- Scope of the filter. 'file' filters by source video properties, 'segment' filters by segment properties. Only duration_seconds is supported with segment scope. file: type: array description: Filter by file properties items: allOf: - $ref: '#/components/schemas/SearchFilterCriteria' - type: object properties: path: type: string enum: - bytes - filename - uri - created_at - id source_metadata: type: array description: >- 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. (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). items: $ref: '#/components/schemas/SearchFilterCriteria' EntityBackedKnowledgeConfig: type: object description: >- Configuration for entity-backed knowledge. Required when `type` is `entity_backed_knowledge`. Contains entity collections with pre-extracted structured data and optional domain context. required: - entity_collections properties: entity_collections: type: array minItems: 1 description: >- 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. items: $ref: '#/components/schemas/EntityCollectionConfig' description: type: string maxLength: 2000 description: >- 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" ResponseAnnotation: type: object required: - type - file_id - start_time properties: type: type: string enum: - cloudglue_citation description: The type of annotation collection_id: type: string format: uuid description: >- The collection containing the cited content. Present when using `collections` source; omitted for `files` and `default` sources. file_id: type: string format: uuid description: The file containing the cited content segment_id: type: string format: uuid description: >- The specific segment cited. Present when a matching segment is found. start_time: type: number description: Start time of the cited content in seconds end_time: type: number description: >- End time of the cited segment in seconds. Present when a matching segment is found. context: type: string description: The text context of the citation relevant_sources: type: array items: type: string description: >- Relevant source descriptions (included when 'cloudglue_citations.media_descriptions' is requested) visual_scene_description: type: array items: type: string description: >- Visual descriptions (included when 'cloudglue_citations.media_descriptions' is requested) scene_text: type: array items: type: string description: >- On-screen text (included when 'cloudglue_citations.media_descriptions' is requested) speech: type: array items: type: string description: >- Speech transcripts (included when 'cloudglue_citations.media_descriptions' is requested) audio_description: type: array items: type: string description: >- Audio descriptions (included when 'cloudglue_citations.media_descriptions' is requested) SearchFilterCriteria: type: object required: - path - operator properties: path: type: string description: JSON path for the field to filter on operator: type: string enum: - NotEqual - Equal - LessThan - GreaterThan - ContainsAny - ContainsAll - In - Like description: Comparison operator to apply valueText: type: string description: >- Text value for scalar comparison (used with NotEqual, Equal, LessThan, GreaterThan, Like) valueTextArray: type: array items: type: string description: >- Array of values for array comparisons (used with ContainsAny, ContainsAll, In) EntityCollectionConfig: type: object description: >- Configuration for an entity collection used with `nimbus-002-preview`. Contains structured, pre-extracted data from the same videos as the main media collection. required: - collection_id properties: name: type: string description: >- 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: type: string description: >- 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: type: string format: uuid description: >- UUID of the entity collection. Must be an existing collection of type `entities`. securitySchemes: bearerAuth: type: http scheme: bearer ````