openapi: 3.0.1 info: title: Fetch Hive Public API version: v1 description: Customer-facing Fetch Hive API endpoints for public API keys. servers: - url: https://api.fetchhive.com paths: /v1/public/workspaces/{workspace_id}/agents/{id}: parameters: - name: workspace_id in: path required: true description: Workspace UUID schema: type: string format: uuid - name: id in: path required: true description: Agent UUID schema: type: string format: uuid get: summary: Get an agent tags: - Agents security: - bearer_auth: [] description: Returns a single active agent belonging to the requested workspace. responses: '200': description: agent returned content: application/json: schema: type: object properties: agent: type: object required: - agent '401': description: unauthorized content: application/json: schema: $ref: '#/components/schemas/error_response' '404': description: workspace not found content: application/json: schema: $ref: '#/components/schemas/error_response' '422': description: agent not found content: application/json: schema: type: object properties: error: type: string example: Agent not found. required: - error patch: summary: Update an agent tags: - Agents security: - bearer_auth: [] description: Updates an existing agent in the requested workspace. parameters: [] responses: '200': description: agent updated content: application/json: schema: type: object properties: message: type: string example: Successfully updated an agent. agent: type: object required: - message - agent '401': description: unauthorized content: application/json: schema: $ref: '#/components/schemas/error_response' '404': description: workspace not found content: application/json: schema: $ref: '#/components/schemas/error_response' '422': description: agent not found content: application/json: schema: type: object properties: error: type: string example: Agent not found. required: - error requestBody: content: application/json: schema: type: object properties: agent: type: object properties: name: type: string example: Updated Agent llm_model: type: string example: gpt-4.1-mini model_type: type: string example: hosted description: type: string example: A helpful assistant instruction_prompt: type: string example: You are a helpful assistant temperature: type: number example: 0.7 max_token: type: integer example: 1000 max_thinking_token: type: integer example: 1024 anthropic_prompt_cache_ttl: type: string enum: - disabled - 5m - 1h reasoning_effort: type: string enum: - low - medium - high - minimal - xhigh - max tool_choice: type: string enum: - none - auto - required required: - agent required: true delete: summary: Delete an agent tags: - Agents security: - bearer_auth: [] description: Destroys the agent record. responses: '200': description: agent deleted content: application/json: schema: type: object properties: message: type: string example: Agent deleted required: - message '401': description: unauthorized content: application/json: schema: $ref: '#/components/schemas/error_response' '422': description: agent not found content: application/json: schema: type: object properties: error: type: string example: Agent not found. required: - error /v1/public/workspaces/{workspace_id}/agents: parameters: - name: workspace_id in: path required: true description: Workspace UUID schema: type: string format: uuid get: summary: List public workspace agents tags: - Agents security: - bearer_auth: [] description: Returns standalone agents scoped to the requested public API workspace. responses: '200': description: agents returned content: application/json: schema: type: object properties: agents: type: array items: type: object required: - agents '401': description: unauthorized content: application/json: schema: $ref: '#/components/schemas/error_response' '404': description: workspace not found content: application/json: schema: $ref: '#/components/schemas/error_response' post: summary: Create an agent tags: - Agents security: - bearer_auth: [] description: Creates a new agent in the requested workspace. parameters: [] responses: '200': description: agent created content: application/json: schema: type: object properties: message: type: string example: Successfully created an agent. agent: type: object required: - message - agent '401': description: unauthorized content: application/json: schema: $ref: '#/components/schemas/error_response' '422': description: invalid LLM model content: application/json: schema: type: object properties: error: type: string required: - error requestBody: content: application/json: schema: type: object properties: agent: type: object properties: name: type: string example: My Agent llm_model: type: string example: gpt-4.1-mini model_type: type: string example: hosted description: type: string example: A helpful assistant instruction_prompt: type: string example: You are a helpful assistant temperature: type: number example: 0.7 max_token: type: string format: uuid required: - name - llm_model - model_type required: - agent required: true /v1/public/workspaces/{workspace_id}/assets: parameters: - name: workspace_id in: path required: true description: Workspace UUID schema: type: string format: uuid get: summary: List public workspace assets tags: - Assets security: - bearer_auth: [] description: Returns assets scoped to the workspace attached to the public API key. responses: '200': description: assets returned content: application/json: schema: type: object properties: assets: type: array items: $ref: '#/components/schemas/asset_object' required: - assets '401': description: unauthorized content: application/json: schema: $ref: '#/components/schemas/error_response' '404': description: workspace not found for API key content: application/json: schema: $ref: '#/components/schemas/error_response' post: summary: Upload a public workspace asset tags: - Assets security: - bearer_auth: [] description: >- Uploads a file and creates a workspace-scoped Asset that can be used as a Hive Agent source. parameters: [] responses: '200': description: asset uploaded content: application/json: schema: type: object properties: message: type: string example: Asset uploaded successfully. asset: $ref: '#/components/schemas/asset_object' required: - message - asset '422': description: no file provided content: application/json: schema: type: object properties: error: type: string message: type: string error_code: type: string example: missing_required_field required: - error - message - error_code requestBody: content: multipart/form-data: schema: type: string format: binary required: true description: The file to upload /v1/public/workspaces/{workspace_id}/knowledge_bases: parameters: - name: workspace_id in: path required: true description: Workspace UUID schema: type: string format: uuid get: summary: List public workspace knowledge bases tags: - Knowledge Bases security: - bearer_auth: [] description: Returns knowledge bases scoped to the requested public API workspace. responses: '200': description: knowledge bases returned content: application/json: schema: type: object properties: knowledge_bases: type: array items: $ref: '#/components/schemas/knowledge_base_object' required: - knowledge_bases '401': description: unauthorized content: application/json: schema: $ref: '#/components/schemas/error_response' '404': description: workspace not found content: application/json: schema: $ref: '#/components/schemas/error_response' post: summary: Create a knowledge base tags: - Knowledge Bases security: - bearer_auth: [] description: Creates a new knowledge base in the requested workspace. parameters: [] responses: '200': description: knowledge base created content: application/json: schema: type: object properties: message: type: string example: Successfully created a knowledge base. knowledge_base: type: object required: - message - knowledge_base '401': description: unauthorized content: application/json: schema: $ref: '#/components/schemas/error_response' requestBody: content: application/json: schema: type: object properties: knowledge_base: type: object properties: name: type: string example: Product Catalog description: type: string example: Searchable product data search_type: type: string enum: - hybrid - vector - full_text example: hybrid search_score_threshold: type: number example: 0.5 search_chunk_limit: type: string format: uuid required: - name required: - knowledge_base required: true /v1/public/workspaces/{workspace_id}/knowledge_bases/{knowledge_base_id}/items: parameters: - name: workspace_id in: path required: true description: Workspace UUID schema: type: string format: uuid - name: knowledge_base_id in: path required: true description: Knowledge base UUID schema: type: string format: uuid get: summary: List public workspace knowledge base items tags: - Knowledge Base Items security: - bearer_auth: [] description: >- Returns items for a knowledge base in the requested public API workspace. responses: '200': description: knowledge base items returned content: application/json: schema: type: object properties: knowledge_base_items: type: array items: type: object properties: id: type: string format: uuid name: type: string knowledge_base_id: type: string format: uuid item_type: type: string run_status: type: string status: type: string required: - id - name - knowledge_base_id - item_type - run_status - status required: - knowledge_base_items '401': description: unauthorized content: application/json: schema: $ref: '#/components/schemas/error_response' '422': description: knowledge base not found in workspace content: application/json: schema: $ref: '#/components/schemas/error_response' /v1/public/workspaces/{workspace_id}/knowledge_bases/{knowledge_base_id}: parameters: - name: workspace_id in: path required: true description: Workspace UUID schema: type: string format: uuid - name: knowledge_base_id in: path required: true description: Knowledge base UUID schema: type: string format: uuid get: summary: Get a knowledge base tags: - Knowledge Bases security: - bearer_auth: [] description: >- Returns a single active knowledge base belonging to the requested workspace. responses: '200': description: knowledge base returned content: application/json: schema: type: object properties: knowledge_base: type: object required: - knowledge_base '401': description: unauthorized content: application/json: schema: $ref: '#/components/schemas/error_response' '422': description: knowledge base not found content: application/json: schema: type: object properties: error: type: string example: Knowledge base not found. required: - error patch: summary: Update a knowledge base tags: - Knowledge Bases security: - bearer_auth: [] description: >- Updates name, description, or search settings of an existing knowledge base. parameters: [] responses: '200': description: knowledge base updated content: application/json: schema: type: object properties: message: type: string example: Successfully updated a knowledge base. knowledge_base: type: object required: - message - knowledge_base '401': description: unauthorized content: application/json: schema: $ref: '#/components/schemas/error_response' '422': description: knowledge base not found content: application/json: schema: type: object properties: error: type: string example: Knowledge base not found. required: - error requestBody: content: application/json: schema: type: object properties: knowledge_base: type: object properties: name: type: string example: Updated Name description: type: string search_type: type: string enum: - hybrid - vector - full_text search_score_threshold: type: number search_chunk_limit: type: integer required: true delete: summary: Delete a knowledge base tags: - Knowledge Bases security: - bearer_auth: [] description: >- Marks a knowledge base for deletion. Cleanup continues asynchronously in the background. responses: '200': description: knowledge base marked for deletion content: application/json: schema: type: object properties: message: type: string example: Knowledge base marked for deletion required: - message '401': description: unauthorized content: application/json: schema: $ref: '#/components/schemas/error_response' /v1/public/workspaces/{workspace_id}/knowledge_bases/{knowledge_base_id}/search: parameters: - name: workspace_id in: path required: true description: Workspace UUID schema: type: string format: uuid - name: knowledge_base_id in: path required: true description: Knowledge base UUID schema: type: string format: uuid post: summary: Search a knowledge base tags: - Knowledge Bases security: - bearer_auth: [] description: > Performs a vector, full-text, or hybrid search against the knowledge base. Returns matching chunks above the configured score threshold. parameters: [] responses: '200': description: search results returned content: application/json: schema: type: object properties: message: type: string example: Successfully ran a search on a knowledge base. response: type: object required: - message - response '401': description: unauthorized content: application/json: schema: $ref: '#/components/schemas/error_response' '422': description: invalid search type content: application/json: schema: type: object properties: error: type: string example: Invalid search type. required: - error requestBody: content: application/json: schema: type: object properties: search_query: type: string example: How do I reset my password? search_type: type: string enum: - hybrid - vector - full_text example: hybrid search_chunk_limit: type: integer minimum: 1 maximum: 20 example: 5 search_score_threshold: type: number minimum: 0 maximum: 1 example: 0.5 required: - search_query - search_type - search_chunk_limit - search_score_threshold required: true /v1/public/models: get: summary: List active models tags: - Models security: - bearer_auth: [] description: > Returns all active (non-deprecated) LLM and image-generation models available in Fetch Hive as a flat array. Excludes embedding-only models. `provider` identifies the underlying model maker (e.g. `openai`, `anthropic`, `minimaxai`). `model_type` is `"llm"` for chat/text models and `"image_generation"` for models that generate images. `is_vision` means a model accepts image input; `is_image_generation` means a model generates images. `is_reasoning` is `true` when the model supports reasoning capabilities. responses: '200': description: models returned content: application/json: schema: type: array items: type: object properties: id: type: string example: gpt-4.1 name: type: string example: GPT 4.1 slug: type: string example: gpt-4-1 provider: type: string example: openai provider_name: type: string example: OpenAI context_limit: type: integer example: 1047576 model_type: type: string example: llm enum: - llm - image_generation is_image_generation: type: boolean example: false is_vision: type: boolean example: true is_reasoning: type: boolean example: false is_tool_calling: type: boolean example: true is_json_schema: type: boolean example: true required: - id - name - slug - provider - provider_name - context_limit - model_type - is_image_generation - is_vision - is_reasoning - is_tool_calling - is_json_schema '401': description: unauthorized content: application/json: schema: $ref: '#/components/schemas/error_response' /v1/public/requests/{id}: parameters: - name: id in: path required: true description: >- Request ID from a Fetch Hive API response (for example, `req_019b1ad1193763f2367afc4cda5ab9df`). schema: type: string get: summary: Get a request tags: - Requests security: - bearer_auth: [] description: > Returns the status, type, and timing metadata for a run. Pass the `request_id` returned when you invoked a prompt, workflow, agent, or Hive Agent. responses: '200': description: request returned content: application/json: schema: type: object properties: id: type: string format: uuid request_id: type: string example: req_019b1ad1193763f2367afc4cda5ab9df status: type: string example: completed request_type: type: string example: prompt_completion requestable_type: type: string nullable: true example: Completion requestable_id: type: string format: uuid nullable: true message: type: string nullable: true generated_at: type: string format: date-time nullable: true started_at: type: string format: date-time nullable: true ended_at: type: string format: date-time nullable: true metadata: type: object additionalProperties: true user_metadata: type: object additionalProperties: true data: type: object nullable: true additionalProperties: true required: - request_id - status - request_type '401': description: unauthorized content: application/json: schema: $ref: '#/components/schemas/error_response' '404': description: request not found content: application/json: schema: type: object properties: error: type: string example: Request not found required: - error /v1/public/search_services/countries: get: summary: List public search-service country catalogs tags: - Search Services security: [] description: > Returns the country catalogs used by public search workflow services. This endpoint is unauthenticated and exposes the value each service expects for location/country configuration. responses: '200': description: country catalogs returned content: application/json: schema: type: object properties: services: type: array items: type: object properties: service: type: string example: google_ai_overview name: type: string example: Google AI Overview country_value_field: type: string example: google_location_name country_value_format: type: string enum: - country_name - alpha2 countries: type: array items: type: object properties: country_name: type: string example: United States alpha2: type: string example: US value: type: string example: US required: - country_name - alpha2 - value required: - service - name - country_value_field - country_value_format - countries required: - services /v1/public/search_services/{service}/countries: get: summary: Retrieve public search-service country catalog tags: - Search Services security: [] description: | Returns the country catalog for one supported search workflow service. Use each country object's `value` field when configuring that service. parameters: - name: service in: path required: true description: Search workflow service key. schema: type: string enum: - google_search - google_news - google_ai_mode - google_ai_overview - bing_search responses: '200': description: Bing Search country catalog returned content: application/json: schema: type: object properties: service: type: string example: google_ai_overview name: type: string example: Google AI Overview country_value_field: type: string example: google_location_name country_value_format: type: string enum: - country_name - alpha2 countries: type: array items: type: object properties: country_name: type: string example: United States alpha2: type: string example: US value: type: string example: US required: - country_name - alpha2 - value required: - service - name - country_value_field - country_value_format - countries '404': description: unsupported service content: application/json: schema: type: object properties: error: type: string example: unsupported_service supported_services: type: array items: type: string example: - google_search - google_news - google_ai_mode - google_ai_overview - bing_search required: - error components: securitySchemes: bearer_auth: type: http scheme: bearer description: 'Workspace API key sent as `Authorization: Bearer `.' schemas: asset_object: type: object properties: id: type: string format: uuid file_name: type: string example: image.png file_url: type: string example: https://cdn.fetchhive.com/image.png file_type: type: string example: image/png file_size: type: integer example: 204800 asset_type: type: string example: image workspace_id: type: string format: uuid nullable: true uploaded_at: type: string format: date-time error_message: type: string nullable: true required: - id - file_name - file_url - asset_type - uploaded_at error_response: type: object properties: error: type: string example: Invalid access. required: - error knowledge_base_object: type: object properties: id: type: string format: uuid name: type: string example: My Knowledge Base description: type: string nullable: true data_item_count: type: integer example: 0 search_score_threshold: type: string example: '0.5' search_chunk_limit: type: integer example: 5 generated_at: type: string format: date-time nullable: true status: type: string example: active search_type: type: string example: hybrid is_active: type: boolean example: true is_archived: type: boolean example: false is_hybrid_search: type: boolean example: true is_vector_search: type: boolean example: false is_full_text_search: type: boolean example: false required: - id - name - data_item_count - search_score_threshold - search_chunk_limit - status - search_type - is_active - is_archived - is_hybrid_search - is_vector_search - is_full_text_search