> ## Documentation Index > Fetch the complete documentation index at: https://chatobserver.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Create an imported dataset > Manage schedules, transfers, destinations and import workflows. Required scopes: `metrics:write`. ## OpenAPI ````yaml POST /api/v2/metrics/imports openapi: 3.1.1 info: title: chatobserver public API version: '2026-09-09' description: >- Track AI visibility, manage prompts, inspect collected answers and citations, and integrate workspace data with your own tools. Visibility endpoints use workspace API keys. Data endpoints use scoped service-account keys; spreadsheet client endpoints use authorised client sessions. See the authentication guide for each credential type. contact: name: chatobserver support url: https://chatobserver.com/contact email: support@chatobserver.com servers: - url: https://app.chatobserver.com description: Production API security: - WorkspaceKey: [] - BearerKey: [] tags: - name: Workspace description: Validate access and list the workspace project and available platforms. - name: Prompts description: Create, schedule, organise, activate and retrieve tracked prompts. - name: Answers description: Retrieve collected AI answers, their analysis and visibility trends. - name: Brands description: Manage brands and compare their visibility in AI answers. - name: Sources and citations description: Analyse cited domains, pages and ownership across answers. - name: Visitor analytics description: Read website visitor and crawler analytics for the workspace. - name: Content opportunities description: Retrieve content-gap findings and recommendations for tracked prompts. - name: Usage description: Read workspace consumption and allowance summaries. - name: Data connections description: Discover authorised connections, source accounts and connector catalogues. - name: Data queries description: >- Create versioned queries, publish definitions and inspect integration contracts. - name: Data operations description: >- Execute, validate, cancel and inspect operations and page through result rows. - name: Data delivery description: Manage schedules, transfers, destinations and import workflows. - name: Data definitions description: Manage reusable definitions and their immutable versions. - name: Data webhooks description: >- Configure event delivery, inspect deliveries, replay events and rotate secrets. - name: Client authorisation description: Authorise spreadsheet clients using a user-approved challenge exchange. - name: Spreadsheet clients description: >- Access document-bound client sessions, queries, schedules, bindings and write claims. - name: AI visibility audits description: Create website visibility audits and retrieve their report links. - name: Version 1 description: Integrate with the version 1 visibility and analytics endpoints. paths: /api/v2/metrics/imports: post: tags: - Data delivery summary: Create an imported dataset description: >- Manage schedules, transfers, destinations and import workflows. Required scopes: `metrics:write`. operationId: postV2MetricsImports parameters: - name: Idempotency-Key in: header required: true schema: type: string minLength: 16 maxLength: 160 pattern: ^[A-Za-z0-9:_-]+$ description: >- Unique key for one logical command. Reuse it only when retrying the same request and payload. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/postV2MetricsImportsRequest' responses: '200': description: Successful response. content: application/json: schema: $ref: '#/components/schemas/postV2MetricsImportsResponse200' '201': description: Created successfully. content: application/json: schema: $ref: '#/components/schemas/postV2MetricsImportsResponse201' default: description: >- Request failed. Inspect the error code and request identifier; retry only when the failure is retryable. content: application/json: schema: anyOf: - $ref: '#/components/schemas/DataError' - $ref: '#/components/schemas/ApiError' components: schemas: postV2MetricsImportsRequest: type: object properties: name: type: string minLength: 1 maxLength: 150 source: anyOf: - type: object properties: kind: type: string const: manual_upload allowedFormats: type: array items: enum: - csv - parquet - tsv - xlsx - jsonl type: string required: - kind - allowedFormats - type: object properties: kind: type: string const: authenticated_file connectionVersionId: type: string providerPath: type: string expectedFormat: enum: - csv - parquet - tsv - xlsx - jsonl type: string required: - kind - connectionVersionId - providerPath - expectedFormat - type: object properties: kind: type: string const: email_intake intakeId: type: string required: - kind - intakeId mapping: type: object properties: name: type: string minLength: 1 maxLength: 150 definition: type: object properties: columns: type: array items: type: object properties: type: enum: - string - number - boolean - integer - date - json - duration - url - percent - currency - datetime - decimal - image_url type: string trim: anyOf: - type: boolean const: false - type: boolean const: true nullable: anyOf: - type: boolean const: false - type: boolean const: true label: type: string minLength: 1 maxLength: 160 source: anyOf: - type: object properties: value: type: string kind: type: string const: header required: - value - kind - type: object properties: value: type: number kind: type: string const: position required: - value - kind fieldId: type: string minLength: 1 maxLength: 256 blankAsNull: anyOf: - type: boolean const: false - type: boolean const: true dateFormat: anyOf: - type: 'null' - type: string const: iso - type: string const: yyyy-MM-dd - type: string const: MM/dd/yyyy - type: string const: dd/MM/yyyy - type: string const: yyyy-MM-dd HH:mm:ss - type: string const: MM/dd/yyyy HH:mm:ss - type: string const: dd/MM/yyyy HH:mm:ss locale: anyOf: - type: 'null' - type: string minLength: 2 maxLength: 35 invalidValuePolicy: enum: - reject_file - quarantine_row - use_null - use_default type: string defaultValue: anyOf: - type: 'null' - type: string - type: number - type: boolean const: false - type: boolean const: true - type: array items: anyOf: - type: 'null' - type: string - type: number - type: boolean const: false - type: boolean const: true - $ref: '#/components/schemas/ContractType54284' - type: object properties: {} additionalProperties: $ref: '#/components/schemas/ContractType54286' - type: object properties: {} additionalProperties: anyOf: - type: 'null' - type: string - type: number - type: boolean const: false - type: boolean const: true - type: array items: $ref: '#/components/schemas/ContractType54286' - $ref: '#/components/schemas/ContractType54285' required: - type - trim - nullable - label - source - fieldId - blankAsNull - dateFormat - locale - invalidValuePolicy additionalProperties: false minItems: 1 maxItems: 5000 schemaVersion: type: number const: 1 sheetName: anyOf: - type: 'null' - type: string minLength: 1 maxLength: 255 headerRow: anyOf: - type: 'null' - type: integer exclusiveMinimum: 0 maximum: 10000 firstDataRow: type: integer exclusiveMinimum: 0 maximum: 10001 delimiter: anyOf: - type: 'null' - type: string const: ',' - type: string const: "\t" - type: string const: ; - type: string const: '|' encoding: type: string const: utf-8 unknownColumnPolicy: enum: - ignore - reject type: string missingColumnPolicy: enum: - use_null - use_default - reject type: string formulaInjectionPolicy: enum: - reject - escape type: string required: - columns - schemaVersion - sheetName - headerRow - firstDataRow - delimiter - encoding - unknownColumnPolicy - missingColumnPolicy - formulaInjectionPolicy additionalProperties: false description: anyOf: - type: 'null' - type: string maxLength: 4000 default: null required: - name - definition additionalProperties: false updatePolicy: type: object properties: name: type: string minLength: 1 maxLength: 150 definition: type: object properties: mode: enum: - replace - append - incremental type: string schemaVersion: type: number const: 1 keyFieldIds: type: array items: type: string minLength: 1 maxLength: 256 maxItems: 50 cursorFieldId: anyOf: - type: 'null' - type: string minLength: 1 maxLength: 256 duplicatePolicy: enum: - reject - keep_first - keep_last type: string lateArrivalLookback: anyOf: - type: 'null' - type: object properties: count: type: integer exclusiveMinimum: 0 maximum: 366 unit: enum: - hour - day - week type: string required: - count - unit additionalProperties: false schemaDriftPolicy: enum: - locked - additive - review_required type: string required: - mode - schemaVersion - keyFieldIds - cursorFieldId - duplicatePolicy - lateArrivalLookback - schemaDriftPolicy additionalProperties: false description: anyOf: - type: 'null' - type: string maxLength: 4000 default: null required: - name - definition additionalProperties: false retentionPolicy: type: object properties: name: type: string minLength: 1 maxLength: 150 definition: type: object properties: schemaVersion: type: number const: 1 residency: type: string minLength: 1 maxLength: 64 sourceRetentionDays: type: integer minimum: 1 maximum: 365 versionRetentionDays: type: integer minimum: 1 maximum: 3650 quarantineRetentionDays: type: integer minimum: 1 maximum: 365 maximumRetainedVersions: type: integer minimum: 1 maximum: 1000 legalHold: anyOf: - type: boolean const: false - type: boolean const: true deleteSourceAfterNormalization: anyOf: - type: boolean const: false - type: boolean const: true required: - schemaVersion - residency - sourceRetentionDays - versionRetentionDays - quarantineRetentionDays - maximumRetainedVersions - legalHold - deleteSourceAfterNormalization additionalProperties: false description: anyOf: - type: 'null' - type: string maxLength: 4000 default: null required: - name - definition additionalProperties: false maximumRows: type: integer exclusiveMinimum: 0 maximum: 10000000 maximumBytes: type: integer exclusiveMinimum: 0 maximum: 10737418240 malformedRowPolicy: enum: - reject_file - quarantine_rows type: string description: anyOf: - type: 'null' - type: string maxLength: 4000 default: null visibility: type: string const: workspace description: Service-account resources must be visible to the workspace. publish: anyOf: - type: boolean const: false - type: boolean const: true default: false qualityRules: type: array items: anyOf: - type: object properties: id: type: string kind: type: string const: not_null severity: enum: - error - warning type: string fieldId: type: string required: - id - kind - severity - fieldId - type: object properties: id: type: string kind: type: string const: unique severity: enum: - error - warning type: string fieldIds: type: array items: type: string required: - id - kind - severity - fieldIds - type: object properties: values: type: array items: {} id: type: string kind: type: string const: accepted_values severity: enum: - error - warning type: string fieldId: type: string required: - values - id - kind - severity - fieldId - type: object properties: minimum: anyOf: - type: 'null' - type: number maximum: anyOf: - type: 'null' - type: number id: type: string kind: type: string const: row_count severity: enum: - error - warning type: string required: - minimum - maximum - id - kind - severity maxItems: 250 default: [] required: - name - source - mapping - updatePolicy - retentionPolicy - maximumRows - maximumBytes - malformedRowPolicy additionalProperties: false postV2MetricsImportsResponse200: type: object properties: data: type: object properties: actorId: type: string importedDatasetId: type: string importedDatasetVersionId: type: string mappingId: type: string mappingVersionId: type: string updatePolicyId: type: string updatePolicyVersionId: type: string retentionPolicyId: type: string retentionPolicyVersionId: type: string versionStatus: type: string required: - actorId - importedDatasetId - importedDatasetVersionId - mappingId - mappingVersionId - updatePolicyId - updatePolicyVersionId - retentionPolicyId - retentionPolicyVersionId - versionStatus replayed: anyOf: - type: boolean const: false - type: boolean const: true required: - data - replayed postV2MetricsImportsResponse201: type: object properties: data: type: object properties: actorId: type: string importedDatasetId: type: string importedDatasetVersionId: type: string mappingId: type: string mappingVersionId: type: string updatePolicyId: type: string updatePolicyVersionId: type: string retentionPolicyId: type: string retentionPolicyVersionId: type: string versionStatus: type: string required: - actorId - importedDatasetId - importedDatasetVersionId - mappingId - mappingVersionId - updatePolicyId - updatePolicyVersionId - retentionPolicyId - retentionPolicyVersionId - versionStatus replayed: anyOf: - type: boolean const: false - type: boolean const: true required: - data - replayed DataError: type: object properties: error: type: object properties: code: enum: - internal - validation_failed - authentication_required - forbidden - not_found - conflict - precondition_failed - idempotency_conflict - capability_unavailable - connection_unavailable - reauthentication_required - provider_rate_limited - workspace_limit_exceeded - result_expired - operation_failed - temporarily_unavailable type: string fieldPath: type: array items: anyOf: - type: string - type: number parameters: type: object properties: {} additionalProperties: anyOf: - type: 'null' - type: string - type: number - type: boolean const: false - type: boolean const: true repairActions: type: array items: type: string minLength: 1 maxLength: 96 maxItems: 10 requestId: type: string minLength: 1 maxLength: 160 retryable: anyOf: - type: boolean const: false - type: boolean const: true retryAfterSeconds: anyOf: - type: 'null' - type: integer exclusiveMinimum: 0 required: - code - fieldPath - parameters - repairActions - requestId - retryable - retryAfterSeconds additionalProperties: false required: - error additionalProperties: false ApiError: type: object properties: error: type: object properties: code: type: string message: type: string details: {} required: - code - message requestId: type: string required: - error - requestId ContractType54284: type: array items: $ref: '#/components/schemas/ContractType54286' ContractType54286: anyOf: - type: 'null' - type: string - type: number - type: boolean const: false - type: boolean const: true - type: array items: $ref: '#/components/schemas/ContractType54286' - type: object properties: {} additionalProperties: $ref: '#/components/schemas/ContractType54286' ContractType54285: type: object properties: {} additionalProperties: $ref: '#/components/schemas/ContractType54286' securitySchemes: WorkspaceKey: type: apiKey in: header name: x-chatobserver-key description: >- A workspace API key. Data endpoints require a service-account key with the specified scopes. BearerKey: type: http scheme: bearer description: The workspace or service-account API key as a bearer token. ````