{ "openapi": "3.1.0", "info": { "title": "Bigdata Content API", "description": "API for managing and accessing private content documents uploaded by users.", "version": "1.0.0" }, "servers": [ { "url": "https://api.bigdata.com/" } ], "security": [ { "ApiKeyAuth": [] } ], "paths": { "/contents/v1/connectors": { "post": { "tags": [ "Connectors" ], "summary": "Create connector", "description": "We recommend using **[Bigdata Connectors Management](https://platform.bigdata.com/connectors)** on the Developer Platform—the guided experience sets up connectors in **four simple steps**. You can also call this endpoint to register connectors programmatically.\n\nProvide the connector **type**, **label**, and type-specific **config**.\n\nFor **email** connectors, an inbox is created and its address is returned; forward emails from allowed senders to that address to ingest, process and index incoming content.\n\nFor **investment_research** connectors, provide broker credentials and the platform will sync research documents from the broker feed.\n\nFor **sharepoint** (Microsoft SharePoint) connectors, set `\"type\": \"sharepoint\"` and supply **`config.session_id`** only. Contact [support@bigdata.com](mailto:support@bigdata.com) to know more about how to generate this parameter.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorCreatePayload" }, "example": { "type": "email", "label": "Broker Research - Daily Reports", "description": "Collects daily reports from the broker's research team", "share_with_org": false, "enrichments": ["translation"], "config": { "allowed_emails": ["user@example.com", "admin@example.com"] } }, "examples": { "email_connector": { "summary": "Email inbox", "value": { "type": "email", "label": "Analyst Research - Daily Reports", "description": "Collects daily reports from the analyst's research team", "share_with_org": false, "enrichments": ["translation"], "config": { "allowed_emails": ["user@example.com", "admin@example.com"] } } }, "investment_research_connector": { "summary": "Investment research", "value": { "type": "investment_research", "label": "Broker Research Reports", "description": "Collects broker research reports from the broker feed", "share_with_org": false, "enrichments": ["translation"], "config": { "user_id": "user@email.com", "user_password": "password", "date_limit": "2026-01-01 00:00:00+00:00" } } }, "sharepoint_connector": { "summary": "Microsoft SharePoint", "value": { "type": "sharepoint", "label": "Research library – SharePoint", "description": "Ingests files from SharePoint using an OAuth-backed session", "share_with_org": false, "enrichments": ["translation"], "config": { "session_id": "your-oauth-session-token" } } } } } } }, "responses": { "200": { "description": "The created connector. **Email** and **investment_research** responses include the non-secret fields described for each type. **Sharepoint** responses return **`config` as `{}`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Connector" }, "example": { "connector_id": "019a9612-bfad-758c-884e-37dd8c6ad2cb", "user_id": "user_id_001", "org_id": "org_id_001", "share_with_org": true, "label": "Broker Research - Daily Reports", "type": "email", "description": "Collects daily reports from the broker's research team", "config": { "allowed_emails": ["user@example.com", "admin@example.com"], "email_hash": "a1b2c3d4e5f6", "email": "a1b2c3d4e5f6@bigdata.com" }, "created_at": "2026-02-11T11:01:09.574095Z", "updated_at": "2026-02-11T11:01:09.574102Z", "archived": false } } } }, "400": { "description": "Invalid request (e.g. missing required fields, invalid configuration for the connector type)." }, "401": { "description": "Unauthorized - Invalid or missing API key." } } }, "get": { "tags": [ "Connectors" ], "summary": "List connectors", "description": "Returns all connectors that belong to the authenticated user. Use this to discover connector_id values for filtering documents, for update/delete operations, or to trigger a syncronization job on demand. Connector configuration is included. Sensitive fields are never returned.", "responses": { "200": { "description": "List of connector objects in a results array. Each connector includes id, label, type, configuration and timestamps.", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "description": "Connectors in this response. Use connector_id when filtering documents or calling update/delete.", "items": { "$ref": "#/components/schemas/Connector" } } }, "required": [ "results" ] } } } }, "400": { "description": "Bad Request." }, "401": { "description": "Unauthorized - Invalid or missing API key." } } } }, "/contents/v1/connectors/{connector_id}": { "get": { "tags": [ "Connectors" ], "summary": "Get connector by ID", "description": "Returns full details for a single connector by its UUID. Use this to inspect connector metadata and configuration. Credentials and secrets are never included in the response.", "parameters": [ { "name": "connector_id", "in": "path", "required": true, "description": "UUID of the connector (returned when creating or listing connectors).", "schema": { "type": "string", "format": "uuid", "example": "019a9612-bfad-758c-884e-37dd8c6ad2cb" } } ], "responses": { "200": { "description": "The connector object with type-specific **`config`**. For **sharepoint**, **`config`** is always **`{}`** (**`session_id`** is never returned).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Connector" } } } }, "400": { "description": "Invalid request (e.g. malformed connector_id)." }, "401": { "description": "Unauthorized - Invalid or missing API key." }, "404": { "description": "No connector found with this ID, or the user does not have access." } } }, "put": { "tags": [ "Connectors" ], "summary": "Update connector by ID", "description": "Update an existing connector's **label**, **description**, and **share_with_org**. For **email** connectors, you may also update **config** (e.g. `allowed_emails`). For **investment_research** and **sharepoint** connectors, configuration cannot be updated. As a PUT request, required fields follow the schema; leaving out a field can clear or default it. The connector **type** cannot be changed.", "parameters": [ { "name": "connector_id", "in": "path", "required": true, "description": "UUID of the connector to update.", "schema": { "type": "string", "format": "uuid", "example": "019a9612-bfad-758c-884e-37dd8c6ad2cb" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorUpdatePayload" }, "example": { "label": "Broker Research - Daily Reports", "description": "Collects daily reports from the broker's research team", "share_with_org": true, "config": { "allowed_emails": [ "user1@bigdata.com", "user2@bigdata.com" ] } } } } }, "responses": { "200": { "description": "The updated connector. Subsequent ingestion uses the new configuration when applicable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Connector" }, "example": { "connector_id": "019c4c5c-b021-7a72-8651-53e01b8f9334", "user_id": "user_id_001", "org_id": "org_id_001", "share_with_org": true, "label": "Broker Research - Daily Reports", "type": "email", "description": "Collects daily reports from the broker's research team", "config": { "allowed_emails": [ "user1@example.com", "user2@example.com" ] }, "created_at": "2026-02-11T11:01:09.574095Z", "updated_at": "2026-02-11T11:15:30.123456Z", "archived": false } } } }, "400": { "description": "Invalid request (e.g. malformed connector_id or invalid request body)." }, "401": { "description": "Unauthorized - Invalid or missing API key." }, "404": { "description": "No connector found with this ID, or the user does not have access." } } }, "delete": { "tags": [ "Connectors" ], "summary": "Delete connector by ID", "description": "By default, soft-deletes a connector: the connector is marked as archived and will no longer ingest new content; existing documents that were ingested by this connector remain available. The operation is idempotent for an already-archived connector.\n\nTo permanently remove the connector and all related data, add the query parameter `force_delete=true`. This triggers a hard delete flow: all files related to this connector are deleted asynchronously. Once all files are deleted, the connector is removed from the database (final step of the async process). The deletion process is asynchronous.", "parameters": [ { "name": "connector_id", "in": "path", "required": true, "description": "UUID of the connector to archive or to hard-delete when force_delete=true.", "schema": { "type": "string", "format": "uuid", "example": "019a9612-bfad-758c-884e-37dd8c6ad2cb" } }, { "name": "force_delete", "in": "query", "required": false, "description": "If true, triggers a hard delete: all files related to this connector are deleted asynchronously, then the connector is removed from the database. If omitted or false, the connector is soft-deleted (archived) and existing documents remain.", "schema": { "type": "boolean", "default": false } } ], "responses": { "200": { "description": "Without force_delete: the connector object in its archived state; it will no longer accept new content and existing documents are unchanged. With force_delete=true: the request is accepted and the hard delete runs asynchronously (all related files are deleted, then the connector is removed from the database).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Connector" } } } }, "400": { "description": "Invalid request (e.g. malformed connector_id)." }, "401": { "description": "Unauthorized - Invalid or missing API key." }, "404": { "description": "No connector found with this ID, or the user does not have permission to delete it." } } } }, "/contents/v1/connectors/{connector_id}/sync": { "post": { "tags": ["Connectors"], "summary": "Trigger connector sync", "description": "Queues a new synchronization run for an **investment_research** or **sharepoint** connector. For **investment_research**, send a JSON body with **`date_limit`** (calendar date, `YYYY-MM-DD`) so the broker sync includes research from that date onward according to platform rules. For **sharepoint**, send an empty JSON body (`{}`). Only content not already ingested will be synced.", "parameters": [ { "name": "connector_id", "in": "path", "required": true, "description": "UUID of the **investment_research** or **sharepoint** connector to resync.", "schema": { "type": "string", "format": "uuid", "example": "019a9612-bfad-758c-884e-37dd8c6ad2cb" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorSyncRequest" }, "example": { "date_limit": "2026-01-01" } } } }, "responses": { "200": { "description": "Sync request was accepted and queued for the connector.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConnectorSyncResponse" }, "example": { "connector_id": "019a9612-bfad-758c-884e-37dd8c6ad2cb", "date_limit": "2026-01-01", "status": "accepted" } } } }, "400": { "description": "Invalid request (e.g. unsupported connector type, missing or invalid `date_limit` for **investment_research**, or a non-empty body for **sharepoint**)." }, "401": { "description": "Unauthorized - Invalid or missing API key." }, "404": { "description": "No connector found with this ID, or the user does not have access." } } } }, "/contents/v1/documents": { "get": { "tags": [ "Documents" ], "summary": "List documents", "description": "Returns a paginated list of documents that the user has uploaded or that have been shared with their organization. Use the query parameters documented below for filtering. Use the returned document id with Get document, Get annotated document, or Get original document to retrieve metadata or file content.", "parameters": [ { "name": "origin", "in": "query", "required": false, "description": "Restrict to documents from this ingestion source: `email` (email connector), `investment_research` (broker / investment research connector), `sharepoint` (Microsoft SharePoint connector), or `file_upload` (direct upload via POST /documents).", "schema": { "type": "string", "enum": [ "email", "investment_research", "sharepoint", "file_upload" ] } }, { "name": "from_date", "in": "query", "required": false, "description": "Include only documents created on or after this date and time (ISO 8601 format).", "schema": { "type": "string", "format": "date-time" } }, { "name": "ownership", "in": "query", "required": false, "description": "Restrict to documents by ownership: all (default), only documents you own (owned), or only documents shared with you (shared).", "schema": { "type": "string", "enum": [ "all", "shared", "owned" ], "default": "all" } }, { "name": "owner", "in": "query", "required": false, "description": "Restrict to documents uploaded by this user ID.", "schema": { "type": "string" } }, { "name": "page", "in": "query", "required": false, "description": "Page number for pagination (1-based). Use with page_size to navigate results.", "schema": { "type": "integer", "default": 1, "minimum": 1 } }, { "name": "page_size", "in": "query", "required": false, "description": "Number of documents to return per page (1–100). Default 50.", "schema": { "type": "integer", "default": 50, "minimum": 1, "maximum": 100 } }, { "name": "sort_by", "in": "query", "required": false, "description": "Field used to sort the result set (e.g. created_at, file_name, status).", "schema": { "type": "string", "enum": [ "created_at", "updated_at", "file_name", "raw_size", "content_type", "status" ], "default": "created_at" } }, { "name": "sort_order", "in": "query", "required": false, "description": "Sort direction: asc (ascending) or desc (descending). Default desc.", "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc" } }, { "name": "file_name", "in": "query", "required": false, "description": "Filter by file name; case-insensitive partial match.", "schema": { "type": "string" } }, { "name": "rp_collection_id", "in": "query", "required": false, "description": "Restrict to documents in this collection (used for email/attachment grouping).", "schema": { "type": "string" } }, { "name": "connector", "in": "query", "required": false, "description": "Restrict to documents ingested by this connector (UUID).", "schema": { "type": "string" } }, { "name": "tags", "in": "query", "required": false, "description": "Filter by tag names; documents matching any of the given tags are returned (OR logic).", "schema": { "type": "array", "items": { "type": "string" } }, "explode": true, "style": "form" } ], "responses": { "200": { "description": "Paginated list of documents matching the filters. The results array contains document metadata; use each document's id with Get annotated document or Get original document to retrieve file content.", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "description": "Documents in this page. Each item includes id (content_id), file_name, status, connector_id, tags, usage, enrichments_requested, enrichments_applied, and timestamps.", "items": { "$ref": "#/components/schemas/DocumentListItem" } } }, "required": [ "results" ] }, "example": { "results": [ { "id": "E0618D0E9D3A960C1731A620EDE56B5C", "file_name": "Weekly summary report.pdf", "user_id": "user_id_001", "org_id": "org_id_001", "rp_collection_id": "2CBDC7DA8AE42A8A078DECC3C9FCADFB", "rp_source_id": "E5A77C", "raw_size": 18974, "pages": 50, "request_origin": "email", "content_type": "application/pdf", "status": "completed", "shared_with_orgs": [ "org_id_001" ], "created_at": "2026-08-10T14:21:40.333178Z", "updated_at": "2026-08-10T14:21:40.333181Z", "published_at": "2026-08-10T12:00:00Z", "connector_id": "019dbfd9-f1ea-7024-888d-e52af8c87b03", "error_code": null, "file_metadata": null, "tags": [ { "id": "019d448a-8511-75de-b5ff-9770fdf91d4b", "name": "to:user1@email.com" }, { "id": "019e21c9-40c8-7857-ae52-a3b51c84108f", "name": "from:user2@email.com" } ], "usage": { "private_data_tokens": 171079 }, "enrichments_requested": [ "translation" ], "enrichments_applied": [] } ] } } } }, "401": { "description": "Unauthorized - Invalid or missing API key." }, "400": { "description": "Invalid query parameters (e.g. invalid date format, page < 1)." } } }, "post": { "tags": [ "Documents" ], "summary": "Enrich document", "description": "Request a pre-signed URL to upload a document directly to Bigdata.com. The response contains a single-use url and the document id. Send a **PUT request** to that URL with the document file as the body to complete the upload. Bigdata then **enriches** the document (extraction, structure and annotation of the content). By default it is also **indexed** and becomes available for the Search and Research Agent. Set **`no_index`** to skip indexing while keeping the document stored and retrievable, or **`no_store`** to skip indexing and retain the document for only 24 hours after enrichment completes.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "file_name" ], "properties": { "file_name": { "type": "string", "description": "Name of the file being uploaded (e.g. research_report.pdf).", "example": "research_report.pdf" }, "published_ts": { "type": "string", "format": "date-time", "description": "Optional publication date/time for the document (ISO 8601). This date will be used as the reference timestamp for search and retrieval.", "example": "2025-06-15T10:30:00Z" }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Optional list of tag names to apply to the document. Tags can be used to search and filter documents in the Search and Research-Agent services.", "example": ["Research Team"] }, "share_with_org": { "type": "boolean", "description": "If true, all members of your organization can access the file once it is processed. If false, only you can access the processed content.", "example": true }, "enrichments": { "type": "array", "description": "Optional list of enrichments to apply while processing the document. Each value configures the processing pipeline to run an additional step on the content.\n\nSupported enrichments:\n- **`reporting_entities`**: Identifies the document's **reporting company**, using the same concept as the [`ReportingEntity` reporting detail](/getting-started/search/query_filters#reporting-details) in Search. This keeps the reporting entity consistent with the rest of the Bigdata corpus, so you can reliably filter private content, transcripts and filings together.\n- **`translation`**: Translates the document content so non-English material can be searched and analyzed alongside the rest of your corpus. Supports more than 70 languages.", "items": { "type": "string", "enum": ["reporting_entities", "translation"] }, "example": ["translation"] }, "no_store": { "type": "boolean", "description": "If true, the document is not indexed and is only retrievable for 24 hours after enrichment completes, then it is deleted. Use this for single-use processing when you do not want the file retained. `no_store` already skips indexing, so setting `no_index` in the same request has no additional effect.", "example": true }, "no_index": { "type": "boolean", "description": "If true, the document is enriched but not indexed in the vector database. The original and annotated files remain stored and retrievable, but the document is not available in Search or Research Agent.", "example": true } } }, "example": { "file_name": "research_report.pdf", "published_ts": "2025-06-15T10:30:00Z", "tags": ["Research Team"], "share_with_org": true, "enrichments": ["translation"], "no_store": false, "no_index": true } } } }, "responses": { "200": { "description": "Pre-signed URL and document id. PUT the file to the URL to complete the upload; use the id with Get document to poll for status.", "content": { "application/json": { "schema": { "type": "object", "required": ["url", "id"], "properties": { "url": { "type": "string", "format": "uri", "description": "Single-use pre-signed URL. Send a PUT request to this URL with the document file as the body." }, "id": { "type": "string", "description": "Document content ID (32-character uppercase hexadecimal). Use this with Get document to check processing status and perform operations on the document." } } }, "example": { "url": "https://s3.amazonaws.com/com.ravenpack.private-content-drop.smart-topics-prod-nvirginia/uploads/F22BC027BCE166BC89DD2A81358DA2F1?AWSAccessKeyId=...", "id": "F22BC027BCE166BC89DD2A81358DA2F1" } } } }, "400": { "description": "Invalid request body (e.g. missing file_name or invalid format)." }, "401": { "description": "Unauthorized - Invalid or missing API key." } } } }, "/contents/v1/documents/{content_id}": { "get": { "tags": [ "Documents" ], "summary": "Get document metadata", "description": "Returns metadata for a single document by its content ID (the document id returned by List documents). Use this to check status, file_name, connector_id, tags, enrichments_requested, enrichments_applied, usage, and timestamps. To retrieve the actual file content, use Get annotated document (enriched JSON) or Get original document (original file format).", "parameters": [ { "name": "content_id", "in": "path", "required": true, "description": "Content ID of the document: a 32-character uppercase hexadecimal string (MD5-based identifier).", "schema": { "type": "string", "pattern": "^[A-F0-9]{32}$", "example": "E0618D0E9D3A960C1731A620EDE56B5C" } } ], "responses": { "200": { "description": "Document metadata (id, file_name, status, connector_id, tags, etc.). Use Get annotated document or Get original document with this id to download content.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentListItem" }, "example": { "id": "E0618D0E9D3A960C1731A620EDE56B5C", "file_name": "Weekly summary report.pdf", "user_id": "user_id_001", "org_id": "org_id_001", "rp_collection_id": "2CBDC7DA8AE42A8A078DECC3C9FCADFB", "rp_source_id": "E5A77C", "raw_size": 18974, "pages": 50, "request_origin": "email", "content_type": "application/pdf", "status": "completed", "shared_with_orgs": [ "org_id_001" ], "created_at": "2026-08-10T14:21:40.333178Z", "updated_at": "2026-08-10T14:21:40.333181Z", "published_at": "2026-08-10T12:00:00Z", "connector_id": "019dbfd9-f1ea-7024-888d-e52af8c87b03", "error_code": null, "delete_started_ts": null, "file_metadata": null, "tags": [ { "id": "019d448a-8511-75de-b5ff-9770fdf91d4b", "name": "to:user1@email.com" }, { "id": "019e21c9-40c8-7857-ae52-a3b51c84108f", "name": "from:user2@email.com" } ], "usage": { "private_data_tokens": 171079 }, "enrichments_requested": [ "translation" ], "enrichments_applied": [] } } } }, "401": { "description": "Unauthorized - Invalid or missing API key." }, "403": { "description": "You do not have permission to access this document (e.g. not shared with your organization)." }, "404": { "description": "No document found with this content_id." } } }, "patch": { "tags": [ "Documents" ], "summary": "Update document metadata", "description": "Partially update a document's metadata. Send only the fields you want to change.\n\n- **`tags`**: Array of **tag IDs** (UUIDs) to assign to the document. This replaces the document's current tag set, so you can add or remove tags by including the full list you want applied. Each ID must refer to an existing tag (use **POST** `/contents/v1/tags` to create one, or **GET** `/contents/v1/tags` to list IDs). If any ID is invalid, the API returns `400` with error code `INVALID_TAGS_ERROR`.\n- **`share_with_org`**: When `true`, the document is available to all members of your organization. When `false`, only you can access it.", "parameters": [ { "name": "content_id", "in": "path", "required": true, "description": "Content ID of the document to update (32-character uppercase hexadecimal string).", "schema": { "type": "string", "pattern": "^[A-F0-9]{32}$", "example": "E0618D0E9D3A960C1731A620EDE56B5C" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentUpdatePayload" }, "examples": { "updateTags": { "summary": "Replace document tags", "value": { "tags": [ "019e3a99-6952-7dd4-adf5-b0b341959e11" ] } }, "updateSharing": { "summary": "Change organization sharing", "value": { "share_with_org": false } } } } } }, "responses": { "200": { "description": "Updated document metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DocumentListItem" } } } }, "400": { "description": "Invalid request body (e.g. one or more tag IDs do not exist).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" }, "example": { "statusCode": 400, "message": "Invalid tag ids.", "errorCode": "INVALID_TAGS_ERROR", "requestId": "6b7438ed-ecf7-4f1d-acd3-8c662cf96149" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key." }, "403": { "description": "You do not have permission to update this document." }, "404": { "description": "No document found with this content_id." } } }, "delete": { "tags": [ "Documents" ], "summary": "Delete document", "description": "Deletes a target document from the platform. It removes everything: original document, annotated version, and chunks from the vector database.", "parameters": [ { "name": "content_id", "in": "path", "required": true, "description": "Content ID of the document to delete (32-character uppercase hexadecimal string).", "schema": { "type": "string", "pattern": "^[A-F0-9]{32}$", "example": "E0618D0E9D3A960C1731A620EDE56B5C" } } ], "responses": { "200": { "description": "Document deleted successfully.", "content": { "application/json": { "schema": { "type": "object", "nullable": true } } } }, "401": { "description": "Unauthorized - Invalid or missing API key." }, "403": { "description": "You do not have permission to delete this document." }, "404": { "description": "Document not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "example": 404 }, "message": { "type": "string", "example": "Document not found" }, "errorCode": { "type": "string", "example": "PRIVATE_CONTENT_NOT_FOUND" }, "requestId": { "type": "string", "format": "uuid", "example": "9be9e5fe-b72d-45dd-8c4c-5f213f745fcd" } } } } } } } } }, "/contents/v1/documents/{content_id}/annotated": { "get": { "tags": [ "Documents" ], "summary": "Get annotated document", "description": "Returns a time-limited pre-signed URL to download **private** document content in annotated (structured) JSON format. Use this only for documents you ingested via the Content API (connectors or direct upload). When you GET the URL, the response contains document content, metadata and annotations. The URL expires after 24 hours; request a new one if needed.", "parameters": [ { "name": "content_id", "in": "path", "required": true, "description": "Content ID of the document (32-character uppercase hex string).", "schema": { "type": "string", "pattern": "^[A-F0-9]{32}$", "example": "E0618D0E9D3A960C1731A620EDE56B5C" } } ], "responses": { "200": { "description": "The endpoint returns an object containing a pre-signed url. Perform a GET request on that URL to retrieve the annotated document in JSON format. The URL is valid for 24 hours; request a new one if needed.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Pre-signed URL that provides temporary access to the annotated document in JSON format. When you access the URL, you receive the complete document with structure: document (metadata), content (title and body blocks), profiling (processor timestamps), and analytics (document-level metrics, events array, entities array).", "example": "https://content.bigdata.com/classified-documents/E0618D0E9D3A960C1731A620EDE56B5C.json?Expires=1770304237&Signature=abc123...&Key-Pair-Id=K34UQS1JQ2RLGM" }, "document": { "description": "**Returned by URL** - Document metadata including source information, timestamps, and details.", "$ref": "#/components/schemas/PrivateDocument" }, "content": { "description": "**Returned by URL** - Document content including title, body blocks, entities, and sentences.", "$ref": "#/components/schemas/PrivateDocumentContent" }, "profiling": { "description": "**Returned by URL** - Processor timestamps for collection.", "type": "object", "properties": { "collection": { "type": "object", "properties": { "processor_in_timestamp_utc": { "type": "string", "example": "2025-10-22 22:57:42.170" }, "processor_out_timestamp_utc": { "type": "string", "example": "2025-10-22 22:57:42.170" } } } } }, "analytics": { "description": "**Returned by URL** - Document-level analytics, events array, and entities array.", "type": "object", "properties": { "document": { "type": "object", "description": "Document-level analytics (analytics_version, document_type, document_sentiment, etc.)." }, "events": { "type": "array", "description": "Detected events with topic, type, relevance, roles, and sentiment." }, "entities": { "type": "array", "description": "Detected entities with entity_type, entity_name, relevance, and sentiment." } } } }, "required": [ "url" ] }, "examples": { "api_response": { "summary": "API Response", "description": "The endpoint returns a pre-signed URL.", "value": { "url": "https://content.bigdata.com/classified-documents/E0618D0E9D3A960C1731A620EDE56B5C.json?Expires=1770304237&Signature=abc123...&Key-Pair-Id=K34UQS1JQ2RLGM" } }, "document_from_url": { "summary": "Document (returned by URL)", "description": "When you access the URL, you receive the complete document in JSON format with the structure: document (metadata), content (title and body blocks) and analytics (document-level metrics, events array, entities array). For transcript-style documents, the Fetch document OpenAPI example document_from_url describes normalized transcript metadata (participants, reporting fields, timestamps_utc) and offset conventions.", "value": { "document": { "rp_document_id": "E0618D0E9D3A960C1731A620EDE56B5C", "source": { "rp_source_id": "DA0F7F", "name": "User Uploaded Content", "rank": 1 }, "timestamp": "2026-02-03T08:43:02Z", "metadata": { "file_name": "Weekly summary report.eml", "content_type": "message/rfc822" } }, "content": { "title": { "text": "Tesla Inc: Q1 2025 Earnings Call", "sentences": [ { "start": 0, "end": 31, "sentiment": "0.00", "sentiment_confidence": "1.00" } ], "entities": [ { "rp_entity_id": "DD3BB1", "start": 0, "end": 9 } ] }, "body": [ { "type": "TEXT", "text": "The first quarter results were announced today.", "normalized_coordinates": [], "sentences": [ { "start": 0, "end": 46, "sentiment": "0.01", "sentiment_confidence": "0.94" } ], "entities": [ { "rp_entity_id": "DD3BB1", "start": 4, "end": 17 } ] }, { "type": "TABLE", "rows": [ { "cells": [ { "type": "CELL_HEADER", "content": [{ "text": "Quarter" }] }, { "type": "CELL_VALUE", "content": [{ "text": "Q1 2025" }] } ] } ] }, { "type": "LIST_UNORDERED", "entries": [ { "key": "•", "content": [{ "text": "Unordered dummy point" }] } ] }, { "type": "LIST_ORDERED", "entries": [ { "key": "1", "content": [{ "text": "Ordered dummy point" }] } ] } ] }, "profiling": { "collection": { "processor_in_timestamp_utc": "2025-10-22 22:57:42.170", "processor_out_timestamp_utc": "2025-10-22 22:57:42.170" } }, "analytics": { "document": { "analytics_version": "2.0", "analytics_revision_number": 0, "document_type": "TRANSCRIPT-RAW", "document_record_count": 257, "title_similarity_key": "0A4AD1E8BF251E1A90E3B2376E471E07", "document_sentiment": 0.21, "document_sentiment_confidence": 0.65, "composite_sentiment_score": 0.04, "sentiment_impact_projection": -0.2, "stock_tone_sentiment": 0, "earnings_tone_sentiment": 0, "commentary_sentiment": 1, "mergers_acquisitions_sentiment": 0, "corporate_actions_sentiment": 0, "earnings_release_sentiment": 0, "product_key": "EDGE", "realtime": "Y" }, "events": [ { "event_similarity_key": "E7913FBE641945AC0670EEF684B6D8E0", "topic": "business", "group": "products-services", "type": "business-contract", "event_relevance": 77, "roles": [ { "rp_entity_id": "DD3BB1", "category": "business-contract", "fact_level": "fact", "document_record_index": 6, "match_type": "TEMPLATE", "event_sentiment": 0.49, "event_risk": 0.24, "sustainability_sentiment": 0.24, "credit_sentiment": 0.25, "interest_rate_sentiment": 0, "event_detection_distance": 0, "event_text": "Tesla: we entered into new contracts", "rp_event_detected_entity_id": "DD3BB1", "event_detected_entity_name": "Tesla Inc." } ] } ], "entities": [ { "rp_entity_id": "4A6F00", "entity_type": "COMP", "entity_name": "Alphabet Inc.", "country_code": "US", "document_record_index": 217, "entity_hierarchy_level": 1, "entity_detection_type": "direct", "entity_detection_distance": 0, "entity_relevance": 26, "entity_sentiment": 0.25, "entity_sentiment_confidence": 0.05, "entity_text_sentiment": 0.25, "entity_text_sent_confidence": 0.05, "analyst_ratings_sentiment": 0, "multi_stock_sentiment": 0 } ] } } } } } } }, "401": { "description": "Unauthorized - Invalid or missing API key." }, "403": { "description": "You do not have permission to access this document." }, "404": { "description": "No document found with this content_id." } } } }, "/contents/v1/documents/{content_id}/original": { "get": { "tags": [ "Documents" ], "summary": "Get original document", "description": "Returns a time-limited pre-signed URL to download the **private** document's original file as uploaded (e.g. .eml, .pdf). When you GET the URL, the response is the raw file with appropriate Content-Type and Content-Disposition. Use this when you need the native format rather than the annotated JSON. The URL expires after 24 hours; request a new one if needed.", "parameters": [ { "name": "content_id", "in": "path", "required": true, "description": "Content ID of the document (32-character uppercase hex string).", "schema": { "type": "string", "pattern": "^[A-F0-9]{32}$", "example": "E0618D0E9D3A960C1731A620EDE56B5C" } } ], "responses": { "200": { "description": "Object containing a pre-signed url. GET the URL to download the original file; response headers include Content-Type and Content-Disposition for saving the file. The URL is valid for 24 hours.", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri", "description": "Time-limited URL. GET this URL to download the original document; the response is the raw file with appropriate headers." } }, "required": [ "url" ] }, "example": { "url": "https://content.bigdata.com/uploaded-documents/E0618D0E9D3A960C1731A620EDE56B5C?response-content-type=message%2Frfc822&response-content-disposition=attachment%3Bfilename%3DEconomic+events+this+week.eml&Expires=1770304294&Signature=abc123...&Key-Pair-Id=K34UQS1JQ2RLGM" } } } }, "401": { "description": "Unauthorized - Invalid or missing API key." }, "403": { "description": "You do not have permission to access this document." }, "404": { "description": "No document found with this content_id." } } } }, "/contents/v1/tags": { "get": { "tags": [ "Tags" ], "summary": "List tags", "description": "Returns all tags visible to the user's organization, with the number of documents associated with each tag. Use the optional `prefix` query parameter to return only tags whose names start with that string (for example `broker:`, `label:`,`from:`, or `to:`). Use the optional `contains` query parameter to return only tags whose names contain that string (for example `My connector`, `My tag` or `my@email.com`). Tags are created automatically for connectors: `label:Connector Name` for any connector type, `from:user@email.com` / `to:user@email.com` for email and `broker:Broker Name` for investment research connectors.", "parameters": [ { "name": "prefix", "in": "query", "required": false, "description": "Return only tags whose name starts with this prefix. Useful to narrow results: `broker:`, `from:`, or `to:`.", "schema": { "type": "string" } }, { "name": "contains", "in": "query", "required": false, "description": "Return only tags whose name contains this string. Useful to narrow results: `My connector`, `My tag` or `my@email.com`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "List of tag objects in a results array. Each tag includes id, name, and file_count. When `prefix` is set, only tags matching that prefix are included. Use the tag name in the tags query parameter of Search Service or Research Agent to filter by that tag.", "content": { "application/json": { "schema": { "type": "object", "properties": { "results": { "type": "array", "description": "Tags with their document counts. Use name when filtering documents.", "items": { "$ref": "#/components/schemas/TagDetails" } } }, "required": [ "results" ] }, "example": { "results": [ { "id": "019a48b4-e573-7203-945a-2e7c4c164217", "name": "from:user@email.com", "created_at": "2025-11-03T07:53:26.150858Z", "updated_at": "2025-11-03T07:53:26.150859Z", "file_count": 40 }, { "id": "019a3a11-8e6a-7296-afe0-bdfe4779982e", "name": "to:user@email.com", "created_at": "2025-10-31T11:40:20.480070Z", "updated_at": "2025-10-31T11:40:20.480074Z", "file_count": 26 }, { "id": "019b2c22-9f7b-83a7-bfc1-cef58810933f", "name": "broker:Broker Name", "created_at": "2026-04-07T09:30:00.000000Z", "updated_at": "2026-04-07T09:30:00.000000Z", "file_count": 10 } ] } } } }, "401": { "description": "Unauthorized - Invalid or missing API key." } } }, "post": { "tags": [ "Tags" ], "summary": "Create tag", "description": "Creates a custom tag in your organization. Use the returned `id` when assigning tags to a document via **PATCH** `/contents/v1/documents/{content_id}` (pass tag IDs in the `tags` array, not names). Tag names supplied at upload time via **POST** `/contents/v1/documents` are resolved by name; for post-upload changes, use tag IDs from this endpoint or from List tags.\n\n\nIf you include spaces in `tag_name`, they are replaced with underscores in the stored tag name. For example, `testing tag 2` is stored as `testing_tag_2`.\n", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTagPayload" }, "example": { "tag_name": "testing tag 2" } } } }, "responses": { "200": { "description": "The created tag, including its `id` for use when updating document metadata.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TagDetails" }, "example": { "id": "019e3a99-6952-7dd4-adf5-b0b341959e11", "name": "testing tag 2", "created_at": "2026-05-18T10:19:53.044285Z", "updated_at": "2026-05-18T10:19:53.044290Z", "file_count": 0 } } } }, "400": { "description": "Invalid request body (e.g. missing or empty tag_name), or a tag with the same name already exists in your organization." }, "401": { "description": "Unauthorized - Invalid or missing API key." } } } }, "/contents/v1/tags/{tag_id}": { "delete": { "tags": [ "Tags" ], "summary": "Delete tag", "description": "Deletes a custom tag by ID. Any documents linked with this tag will have the association removed.", "parameters": [ { "name": "tag_id", "in": "path", "required": true, "description": "UUID of the tag to delete.", "schema": { "type": "string", "format": "uuid", "example": "019a48b4-e573-7203-945a-2e7c4c164217" } } ], "responses": { "202": { "description": "Tag deleted successfully. Associated documents are updated to remove the tag." }, "401": { "description": "Unauthorized - Invalid or missing API key." }, "404": { "description": "Tag not found.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "example": 404 }, "message": { "type": "string", "example": "Tag not found" }, "errorCode": { "type": "string", "example": "TAG_NOT_FOUND" } } } } } } } } } }, "components": { "securitySchemes": { "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-KEY", "description": "Your API key. Include it in every request as the X-API-KEY header. Create and manage keys in the Developer Platform." } }, "schemas": { "DocumentListItem": { "type": "object", "description": "Metadata for a single document. Returned by List documents and Get document. Use the id (content_id) with Get annotated document or Get original document to retrieve the file content.", "properties": { "id": { "type": "string", "description": "Content ID: unique 32-character uppercase hexadecimal identifier for the document. Use this when calling Get document, Get annotated document, or Get original document.", "example": "E0618D0E9D3A960C1731A620EDE56B5C" }, "file_name": { "type": "string", "description": "Original file name of the uploaded document.", "example": "Weekly summary report.eml" }, "user_id": { "type": "string", "description": "ID of the user who uploaded the document.", "example": "user_id_001" }, "org_id": { "type": "string", "description": "ID of the organization the document belongs to.", "example": "org_id_001" }, "rp_collection_id": { "type": "string", "nullable": true, "description": "ID of the collection the document belongs to. This is applicable only for emails and attachments.", "example": "2CBDC7DA8AE42A8A078DECC3C9FCADFB" }, "rp_source_id": { "type": "string", "nullable": true, "description": "Identifier of the RavenPack source associated with this document. This source is used to filter documents in the Search and Research Agent.", "example": "E5A77C" }, "raw_size": { "type": "integer", "description": "Size of the raw document in bytes.", "example": 18974 }, "pages": { "type": "integer", "nullable": true, "description": "Number of pages in the document when page count is available (for example PDFs).", "example": 50 }, "request_origin": { "type": "string", "description": "Origin of the content ingestion request: how the document entered the platform.", "enum": [ "email", "investment_research", "sharepoint", "file_upload" ] }, "content_type": { "type": "string", "description": "MIME type of the document.", "example": "message/rfc822" }, "status": { "type": "string", "description": "Processing status of the document.", "enum": [ "pending", "processing", "completed", "failed" ] }, "shared_with_orgs": { "type": "array", "description": "List of organization IDs the document is shared with.", "items": { "type": "string" }, "example": [ "org_id_001" ] }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the document was created.", "example": "2026-02-03T08:43:02.729356Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the document was last updated.", "example": "2026-02-03T08:43:02.729359Z" }, "published_at": { "type": "string", "format": "date-time", "description": "Timestamp when the document was published. This is the reference timestamp used for search and retrieval.", "example": "2026-02-03T08:43:02.729359Z" }, "connector_id": { "type": "string", "format": "uuid", "nullable": true, "description": "ID of the connector used to upload the document.", "example": "019a9612-bfad-758c-884e-37dd8c6ad2cb" }, "error_code": { "type": "string", "nullable": true, "description": "Error code if the document processing failed.", "example": null }, "delete_started_ts": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp when document deletion started, if applicable.", "example": null }, "file_metadata": { "type": "object", "nullable": true, "description": "Additional metadata about the file.", "example": null }, "tags": { "type": "array", "description": "Tags associated with the document.", "items": { "$ref": "#/components/schemas/Tag" } }, "usage": { "$ref": "#/components/schemas/DocumentUsage" }, "enrichments_requested": { "type": "array", "description": "Enrichments requested for this document (from direct upload or the connector that ingested it). See [Enrichments](/api-rest/content_introduction#enrichments).", "items": { "type": "string", "enum": ["reporting_entities", "translation"] }, "example": ["translation"] }, "enrichments_applied": { "type": "array", "description": "Enrichments that were successfully applied during processing. Compare with `enrichments_requested` to see what is still pending or was not applied.", "items": { "type": "string", "enum": ["reporting_entities", "translation"] }, "example": [] } }, "required": [ "id", "file_name", "user_id", "org_id", "status", "created_at", "updated_at", "published_at" ] }, "DocumentUsage": { "type": "object", "description": "Usage metering for a private document (Private Content Storage).", "properties": { "private_data_tokens": { "type": "integer", "description": "Private Content Storage tokens consumed by this document after enrichment and indexing. See [Pricing](/getting-started/bigdata_pricing).", "example": 171079 } }, "required": [ "private_data_tokens" ] }, "Tag": { "type": "object", "description": "A tag associated with a document.", "properties": { "id": { "type": "string", "description": "Unique identifier for the tag.", "example": "019a48b4-e574-71d9-a8d9-6a5a86386847" }, "name": { "type": "string", "description": "Name of the tag (e.g. `from:user@email.com` for email; `broker:Broker Name` for investment research).", "example": "from:user@email.com" } }, "required": [ "id", "name" ] }, "TagDetails": { "type": "object", "description": "Detailed information about a tag.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique identifier for the tag.", "example": "019a48b4-e573-7203-945a-2e7c4c164217" }, "name": { "type": "string", "description": "Name of the tag (e.g. `from:user@email.com`, `to:user@email.com`, `broker:Broker Name` or a custom one provided by the user).", "example": "from:user@email.com" }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the tag was created.", "example": "2025-11-03T07:53:26.150858Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the tag was last updated.", "example": "2025-11-03T07:53:26.150859Z" }, "file_count": { "type": "integer", "description": "Number of files associated with this tag.", "example": 40 } }, "required": [ "id", "name", "created_at", "updated_at", "file_count" ] }, "CreateTagPayload": { "type": "object", "description": "Request body for creating a custom tag.", "required": [ "tag_name" ], "properties": { "tag_name": { "type": "string", "description": "Display name for the new tag.", "example": "testing tag 2" } } }, "DocumentUpdatePayload": { "type": "object", "description": "Fields to update on a document. Include only the properties you want to change.", "properties": { "tags": { "type": "array", "items": { "type": "string", "format": "uuid" }, "description": "Tag IDs to assign to the document. Replaces the current tag assignment. Every ID must exist; otherwise the API returns `INVALID_TAGS_ERROR`.", "example": [ "019e3a99-6952-7dd4-adf5-b0b341959e11" ] }, "share_with_org": { "type": "boolean", "description": "If true, all members of your organization can access the document. If false, only you can access it.", "example": false } } }, "ApiError": { "type": "object", "description": "Standard API error response.", "properties": { "statusCode": { "type": "integer", "example": 400 }, "message": { "type": "string", "example": "Invalid tag ids." }, "errorCode": { "type": "string", "example": "INVALID_TAGS_ERROR" }, "requestId": { "type": "string", "format": "uuid", "example": "6b7438ed-ecf7-4f1d-acd3-8c662cf96149" } } }, "Connector": { "type": "object", "description": "An ingestion source (e.g. email inbox, investment research / broker feed, or Microsoft SharePoint). Returned by Create/Get/Update connector and List connectors.", "properties": { "connector_id": { "type": "string", "format": "uuid", "description": "Unique identifier for the connector. Use when updating, deleting, or filtering documents by connector.", "example": "019a9612-bfad-758c-884e-37dd8c6ad2cb" }, "user_id": { "type": "string", "description": "ID of the user who owns the connector.", "example": "user_id_001" }, "org_id": { "type": "string", "description": "ID of the organization the connector belongs to.", "example": "org_id_001" }, "share_with_org": { "type": "boolean", "description": "If true, all members of your organization can access the processed content. If false, only you can access the processed content.", "example": true }, "label": { "type": "string", "description": "Display name for the connector (e.g. for UI or admin lists).", "example": "Broker Research - Daily Reports" }, "type": { "type": "string", "description": "Connector type. Determines the configuration and how content is ingested.", "enum": [ "email", "investment_research", "sharepoint" ] }, "description": { "type": "string", "description": "Optional human-readable description of what the connector is used for.", "example": "Collects daily reports from the broker's research team" }, "enrichments": { "type": "array", "description": "Enrichments applied to content ingested through this connector. Each value adds a step to the processing pipeline.\n\nSupported enrichments:\n- **`reporting_entities`**: Identifies the document's **reporting company**, using the same concept as the [`ReportingEntity` reporting detail](/getting-started/search/query_filters#reporting-details) in Search. This keeps the reporting entity consistent with the rest of the Bigdata corpus, so you can reliably filter private content, transcripts and filings together.\n- **`translation`**: Translates the document content so non-English material can be searched and analyzed alongside the rest of your corpus. Supports more than 70 languages.", "items": { "type": "string", "enum": ["reporting_entities", "translation"] }, "example": ["translation"] }, "config": { "description": "Type-specific settings. Email connectors return inbox and allowed senders; investment research connectors return `user_id` only (never `user_password`); SharePoint connectors return `config` as `{}`.", "nullable": true, "oneOf": [ { "title": "Email", "$ref": "#/components/schemas/EmailConnectorResponseConfig" }, { "title": "Investment research", "$ref": "#/components/schemas/InvestmentResearchConnectorResponseConfig" }, { "title": "SharePoint", "$ref": "#/components/schemas/SharepointConnectorResponseConfig" } ] }, "files_count": { "type": "integer", "description": "Number of files ingested through this connector, when tracked (e.g. investment research sync).", "example": 10 }, "last_sync_at": { "type": "string", "format": "date-time", "nullable": true, "description": "Timestamp of the last sync from the external source, when applicable.", "example": "2026-04-07T09:36:34.195040Z" }, "last_sync_status": { "type": "string", "nullable": true, "description": "Outcome of the last sync (e.g. SUCCESS), when applicable.", "example": "SUCCESS" }, "last_sync_error_msg": { "type": "string", "nullable": true, "description": "Error message from the last sync when it failed; null on success.", "example": null }, "last_sync_count": { "type": "integer", "nullable": true, "description": "Number of items processed in the last sync, when applicable.", "example": 3200 }, "created_at": { "type": "string", "format": "date-time", "description": "Timestamp when the connector was created.", "example": "2026-02-11T11:01:09.574095Z" }, "updated_at": { "type": "string", "format": "date-time", "description": "Timestamp when the connector was last updated.", "example": "2026-02-11T11:01:09.574102Z" }, "archived": { "type": "boolean", "description": "Whether the connector is archived.", "example": false } }, "required": [ "connector_id", "user_id", "org_id", "share_with_org", "label", "type", "created_at", "updated_at", "archived" ] }, "ConnectorCreatePayload": { "type": "object", "description": "Payload for creating a new connector.", "properties": { "type": { "type": "string", "description": "Type of the connector. If type is `email`, an inbox is created for forwarding messages into Bigdata. If type is `investment_research`, provide broker credentials in `config` for automated sync of research documents.", "enum": [ "email", "investment_research", "sharepoint" ] }, "label": { "type": "string", "description": "Display name for the connector (e.g. for admin UIs or List connectors).", "example": "Broker Research - Daily Reports" }, "description": { "type": "string", "description": "Optional short description of what this connector is used for.", "example": "Collects daily reports from the broker's research team" }, "share_with_org": { "type": "boolean", "description": "If true, all members of your organization can access the processed content. If false, only you can access the processed content.", "default": false, "example": false }, "enrichments": { "type": "array", "description": "Optional list of enrichments to apply to content ingested through this connector. Each value configures the processing pipeline to run an additional step on the content.\n\nSupported enrichments:\n- **`reporting_entities`**: Identifies the document's **reporting company**, using the same concept as the [`ReportingEntity` reporting detail](/getting-started/search/query_filters#reporting-details) in Search. This keeps the reporting entity consistent with the rest of the Bigdata corpus, so you can reliably filter private content, transcripts and filings together.\n- **`translation`**: Translates the document content so non-English material can be searched and analyzed alongside the rest of your corpus. Supports more than 70 languages.", "items": { "type": "string", "enum": ["reporting_entities", "translation"] }, "example": ["translation"] }, "config": { "description": "Connector-specific configuration. The structure depends on the connector type.", "nullable": true, "oneOf": [ { "title": "Email", "$ref": "#/components/schemas/EmailConnectorConfig" }, { "title": "Investment research", "$ref": "#/components/schemas/InvestmentResearchConnectorConfig" }, { "title": "SharePoint", "$ref": "#/components/schemas/SharepointConnectorConfig" } ] } }, "required": [ "type", "label", "config" ] }, "ConnectorUpdatePayload": { "type": "object", "description": "Payload for **PUT /contents/v1/connectors/{connector_id}**. Only **email** accepts a **`config`** body; for **investment_research** and **sharepoint**, omit **`config`**.", "properties": { "label": { "type": "string", "description": "New display name for the connector. Required.", "example": "Broker Research - Daily Reports" }, "description": { "type": "string", "description": "New optional description.", "default": "", "example": "Collects daily reports from the broker's research team" }, "share_with_org": { "type": "boolean", "description": "If true, all members of your organization can access the processed content. If false, only you can access the processed content.", "default": false, "example": true }, "config": { "description": "Connector-specific configuration. The structure depends on the connector type.", "nullable": true, "oneOf": [ { "title": "Email", "$ref": "#/components/schemas/EmailConnectorConfig" }, { "title": "Investment research or SharePoint (omit config on PUT)", "type": "null", "description": "Do not send **`config`** when updating **investment_research** or **sharepoint** connectors. Use **`null`** or omit the field when updating only label, description, or sharing." } ] } }, "required": [ "label" ] }, "EmailConnectorConfig": { "type": "object", "description": "Configuration for email connectors.", "properties": { "allowed_emails": { "type": "array", "description": "List of approved email addresses. Only emails from these addresses will be processed.", "items": { "type": "string", "format": "email" }, "default": [], "example": [ "user@example.com", "admin@example.com" ] }, "email_hash": { "type": "string", "description": "Unique hash identifier for the email connector.", "example": "a1b2c3d4e5f6" }, "email": { "type": "string", "format": "email", "description": "The Bigdata inbox address for this connector. Returned after creation; forward emails from allowed_emails to this address to ingest them.", "nullable": true, "example": "connector@bigdata.com" } }, "required": [ "email_hash" ] }, "SharepointConnectorConfig": { "type": "object", "description": "Configuration for SharePoint connectors (for create/update requests).", "properties": { "session_id": { "type": "string", "description": "Token that represents the session authenticated via OAuth. Contact [support@bigdata.com](mailto:support@bigdata.com) if you would like to know more about how to generate this parameter.", "example": "your-oauth-session-token" } }, "required": ["session_id"] }, "EmailConnectorResponseConfig": { "type": "object", "description": "Email connector configuration as returned by the API. Contains allowed_emails and the inbox email address.", "properties": { "allowed_emails": { "type": "array", "description": "Sender addresses that are allowed to send content to this connector.", "items": { "type": "string", "format": "email" }, "example": [ "user@example.com", "admin@example.com" ] }, "email_hash": { "type": "string", "description": "Unique hash identifier for the email connector.", "example": "a1b2c3d4e5f6" }, "email": { "type": "string", "format": "email", "description": "Inbox address to forward emails to; only messages from allowed_emails are processed.", "nullable": true, "example": "connector@bigdata.com" } } }, "InvestmentResearchConnectorConfig": { "type": "object", "description": "Configuration for **investment_research** connectors (create). Use the broker account login supplied by your data provider. `user_password` is write-only and is never returned by the API.", "properties": { "user_id": { "type": "string", "description": "Broker or research portal user id (often an email address).", "example": "user@email.com" }, "user_password": { "type": "string", "format": "password", "description": "Broker or research portal password. Required when creating the connector; never included in list or get responses.", "example": "password" }, "date_limit": { "type": "string", "description": "Optional lower bound for the initial broker sync. The platform includes research from this timestamp onward. Example: `2026-01-01 00:00:00+00:00`.", "example": "2026-01-01 00:00:00+00:00" } }, "required": [ "user_id", "user_password" ] }, "InvestmentResearchConnectorResponseConfig": { "type": "object", "description": "Investment research connector configuration as returned by the API. Only non-secret fields are present.", "properties": { "user_id": { "type": "string", "description": "Broker or research portal user id (often an email address).", "example": "API@ravenpack.com" } }, "required": [ "user_id" ] }, "SharepointConnectorResponseConfig": { "type": "object", "description": "SharePoint connector **`config`** in **List**, **Get**, **Create**, and **Update** responses: always empty. **`session_id`** is accepted only on **POST create** and is **never** present in any response.", "properties": {}, "additionalProperties": false, "maxProperties": 0 }, "ConnectorSyncRequest": { "type": "object", "description": "Body for **POST /contents/v1/connectors/{connector_id}/sync**. For **investment_research** connectors, send **`date_limit`**. For **sharepoint** connectors, send an empty object (`{}`).", "properties": { "date_limit": { "type": "string", "format": "date", "description": "Calendar date (`YYYY-MM-DD`). Required for **investment_research** connectors; retriggers broker synchronization including research from this date forward per platform rules. Must be omitted for **sharepoint** connectors.", "example": "2026-01-01" } } }, "ConnectorSyncResponse": { "type": "object", "description": "Acknowledgement after a sync trigger is accepted.", "properties": { "connector_id": { "type": "string", "format": "uuid", "description": "Connector that was targeted.", "example": "019a9612-bfad-758c-884e-37dd8c6ad2cb" }, "date_limit": { "type": "string", "format": "date", "description": "Echo of the requested date limit. Returned only for **investment_research** connectors.", "example": "2026-01-01" }, "status": { "type": "string", "description": "Processing state of the request (for example `accepted` when queued).", "example": "accepted" } }, "required": ["connector_id", "status"] }, "PrivateDocument": { "type": "object", "description": "Document metadata returned when accessing the annotated document URL.", "properties": { "rp_document_id": { "type": "string", "description": "Internal document identifier", "example": "E0618D0E9D3A960C1731A620EDE56B5C" }, "source": { "$ref": "#/components/schemas/PrivateDocumentSource" }, "timestamp": { "type": "string", "format": "date-time", "description": "Document timestamp in ISO format", "example": "2026-02-03T08:43:02Z" }, "metadata": { "$ref": "#/components/schemas/PrivateDocumentMetadata" } }, "required": [ "rp_document_id", "source", "timestamp", "metadata" ] }, "PrivateDocumentSource": { "type": "object", "description": "Information about the document source.", "properties": { "rp_source_id": { "type": "string", "description": "Identifier of the source system", "example": "DA0F7F" }, "name": { "type": "string", "description": "Source display name", "example": "User Uploaded Content" }, "rank": { "type": "integer", "description": "Ranking classification of the source", "example": 1 } }, "required": [ "rp_source_id", "name", "rank" ] }, "PrivateDocumentMetadata": { "type": "object", "description": "Additional document metadata.", "properties": { "file_name": { "type": "string", "description": "Original file name of the uploaded document", "example": "Weekly summary report.eml" }, "content_type": { "type": "string", "description": "MIME type of the document", "example": "message/rfc822" }, "user_id": { "type": "string", "description": "ID of the user who uploaded the document", "example": "user_id_001" }, "org_id": { "type": "string", "description": "ID of the organization", "example": "org_id_001" } } }, "PrivateDocumentContent": { "type": "object", "description": "Structured content extracted from the document including title and body blocks.", "properties": { "title": { "$ref": "#/components/schemas/ContentTitleBlock" }, "body": { "type": "array", "description": "Array of content blocks extracted from the document", "items": { "$ref": "#/components/schemas/ContentBlock" } } }, "required": [ "title", "body" ] }, "ContentTitleBlock": { "type": "object", "description": "Title content block representing the document title.", "properties": { "text": { "type": "string", "description": "Extracted document title", "example": "Weekly summary report" }, "sentences": { "type": "array", "description": "Sentence segmentation with sentiment analysis", "items": { "$ref": "#/components/schemas/Sentence" } }, "entities": { "type": "array", "description": "Entities detected in the title text", "items": { "$ref": "#/components/schemas/TextEntity" } } }, "required": [ "text" ] }, "ContentBlock": { "type": "object", "description": "A content block (TEXT, TABLE, LIST, etc.)", "properties": { "type": { "type": "string", "description": "Type of content block", "enum": [ "TEXT", "TABLE", "LIST_ORDERED", "LIST_UNORDERED", "HEADING", "FOOTER" ], "example": "TEXT" }, "text": { "type": "string", "description": "Text content (for TEXT blocks)", "example": "The Federal Reserve will meet this week to discuss interest rates." }, "normalized_coordinates": { "type": "array", "description": "Normalized coordinates for the block position", "items": { "type": "number" } }, "sentences": { "type": "array", "description": "Sentence segmentation with sentiment", "items": { "$ref": "#/components/schemas/Sentence" } }, "entities": { "type": "array", "description": "Entities detected in the text", "items": { "$ref": "#/components/schemas/TextEntity" } }, "rows": { "type": "array", "description": "Table rows (for TABLE blocks)", "items": { "type": "object" } }, "entries": { "type": "array", "description": "List entries (for LIST blocks)", "items": { "type": "object" } } }, "required": [ "type" ] }, "Sentence": { "type": "object", "description": "Sentence segmentation information with sentiment analysis.", "properties": { "start": { "type": "integer", "description": "Start character index of the sentence", "example": 0 }, "end": { "type": "integer", "description": "End character index of the sentence", "example": 67 }, "sentiment": { "type": "string", "description": "Sentiment score from -1.00 (negative) to 1.00 (positive)", "example": "0.01" }, "sentiment_confidence": { "type": "string", "description": "Confidence score for sentiment analysis (0.00 to 1.00)", "example": "0.94" } }, "required": [ "start", "end" ] }, "TextEntity": { "type": "object", "description": "An entity detected within the text.", "properties": { "rp_entity_id": { "type": "string", "description": "Bigdata.com unique entity identifier", "example": "4A1B9C" }, "name": { "type": "string", "description": "Display name of the entity", "example": "Federal Reserve" }, "type": { "type": "string", "description": "Entity type classification", "enum": [ "COMPANY", "PERSON", "PLACE", "PRODUCT", "ORGANIZATION", "ETF" ], "example": "ORGANIZATION" }, "start": { "type": "integer", "description": "Start character index of the entity", "example": 4 }, "end": { "type": "integer", "description": "End character index of the entity", "example": 19 } }, "required": [ "rp_entity_id", "start", "end" ] } } } }