> ## Documentation Index > Fetch the complete documentation index at: https://docs.summation.com/llms.txt > Use this file to discover all available pages before exploring further. # Create an authoritative provider snapshot upload > Create a generation-fenced atomic replacement from one provider bulk operation. Use direct upload for an immutable provider result URL, or staged pages for provider-owned cursor fanout. Replaying the same operation is idempotent. ## OpenAPI ````yaml https://api.summation.com/openapi.json post /v1/data-syncs/{sync_id}/snapshots openapi: 3.1.0 info: title: summation-api public API version: 0.1.0 servers: [] security: [] tags: - name: Auth description: Machine authentication for API clients. - name: Tenant description: Organization and tenant context resolved by summation-api. - name: Projects description: Project resources. - name: Conversations description: Conversation and message resources. - name: Reports description: Report resources and report operations. - name: Runs description: Project run history and execution status. - name: Playbooks description: Playbook resources. - name: Files description: Project file resources. - name: Catalog Entries description: Project-scoped data asset attachments. - name: Data Connectors description: Reusable external data source connections. - name: App Connectors description: External app connectors whose tools the agent can use during chat. - name: Tables description: Canonical table metadata and catalog. - name: Views description: Canonical Summation view metadata and catalog. - name: Query Executions description: Read-only SQL query execution. - name: Grid description: Materialized grid status, sync, and lineage. - name: Schedules description: Schedule and schedule run inspection. - name: Workflows description: >- Workflows: what they run, when they run, and where their output is delivered. - name: Verification Tests description: >- Administrative custom verification-test definitions, overlays, and effective-set previews. paths: /v1/data-syncs/{sync_id}/snapshots: post: tags: - Tables summary: Create an authoritative provider snapshot upload description: >- Create a generation-fenced atomic replacement from one provider bulk operation. Use direct upload for an immutable provider result URL, or staged pages for provider-owned cursor fanout. Replaying the same operation is idempotent. operationId: create_snapshot parameters: - name: sync_id in: path required: true schema: type: string minLength: 1 description: Configured source sync receiving the page. title: Sync Id description: Configured source sync receiving the page. requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SnapshotCreateRequest' responses: '201': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/SnapshotCreateResponse' '400': description: Invalid request or unsupported option. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemError' '401': description: Missing, invalid, or expired credentials. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemError' '403': description: Authenticated but missing the required scope. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemError' '404': description: Resource not found or not accessible. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemError' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' '429': description: Rate limit exceeded. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemError' '500': description: Internal server error. content: application/problem+json: schema: $ref: '#/components/schemas/ProblemError' security: - SummationMachineAuth: - tables:append components: schemas: SnapshotCreateRequest: properties: source_operation_id: type: string maxLength: 255 minLength: 1 title: Source Operation Id description: >- Stable provider operation or fanout-manifest identifier used to make snapshot creation idempotent. source_format: type: string const: SHOPIFY_GRAPHQL_JSONL_2026_01 title: Source Format description: >- Versioned provider export format that determines server-side parsing and schema validation. expected_size_bytes: type: integer maximum: 9007199254740991 minimum: 0 title: Expected Size Bytes description: >- Exact bulk-result byte size, or zero when staged pages supply the authoritative manifest. sync_generation: type: string maxLength: 255 minLength: 1 title: Sync Generation description: >- Current installed recipe generation; stale generations cannot create or commit a snapshot. staged_pages: type: boolean title: Staged Pages description: >- Whether the snapshot is assembled from immutable numbered pages instead of one direct upload. default: false additionalProperties: false type: object required: - source_operation_id - source_format - expected_size_bytes - sync_generation title: SnapshotCreateRequest description: One completed provider bulk operation ready for streaming handoff. SnapshotCreateResponse: properties: data: $ref: '#/components/schemas/SnapshotCreateResponseData' description: Authoritative snapshot creation result. type: object required: - data title: SnapshotCreateResponse ProblemError: description: >- Public error envelope (RFC 7807 ``application/problem+json``). Mirrors the body produced by :func:`api_error`. Declaring it in the contract lets generated clients type error handling instead of guessing. properties: type: description: URI reference identifying the problem type. title: Type type: string title: description: Short, human-readable summary of the problem type. title: Title type: string status: description: HTTP status code. title: Status type: integer detail: description: Human-readable explanation specific to this occurrence. title: Detail type: string code: description: Stable, machine-readable error code. title: Code type: string request_id: description: Correlation id, echoed in the x-request-id header. title: Request Id type: string required: - type - title - status - detail - code - request_id title: ProblemError type: object HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError SnapshotCreateResponseData: properties: snapshot: $ref: '#/components/schemas/SnapshotPublic' description: Created or replayed authoritative snapshot. replayed: type: boolean title: Replayed description: Whether this operation returned an existing idempotent snapshot. uploadUrl: anyOf: - type: string - type: 'null' title: Uploadurl description: >- Signed direct-upload URL; absent when the snapshot uses staged pages. expiresInSeconds: anyOf: - type: integer - type: 'null' title: Expiresinseconds description: Seconds until the signed direct-upload URL expires. additionalProperties: false type: object required: - snapshot - replayed title: SnapshotCreateResponseData ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type type: object required: - loc - msg - type title: ValidationError SnapshotPublic: properties: id: type: string title: Id description: Authoritative snapshot identifier. mode: type: string const: REPLACE title: Mode description: Atomic mutation mode used by authoritative snapshots. status: type: string enum: - CREATING - UPLOADING - COMMITTING - RUNNING - SUCCEEDED - FAILED - ABORTED title: Status description: >- Current snapshot lifecycle state; SUCCEEDED, FAILED, and ABORTED are terminal. sourceWatermark: anyOf: - type: string - type: 'null' title: Sourcewatermark description: >- Provider operation identifier represented by the snapshot, when present. expectedSizeBytes: anyOf: - type: string - type: 'null' title: Expectedsizebytes description: >- Expected object size encoded as a decimal string to preserve 64-bit precision. expectedSha256: anyOf: - type: string - type: 'null' title: Expectedsha256 description: Expected object SHA-256 digest when the ingestion mode supplies one. rowsBefore: anyOf: - type: string - type: 'null' title: Rowsbefore description: Destination row count before the authoritative replacement. rowsAfter: anyOf: - type: string - type: 'null' title: Rowsafter description: Destination row count after the authoritative replacement. rowsInserted: anyOf: - type: string - type: 'null' title: Rowsinserted description: >- Rows newly inserted, when the ingestion mode computes semantic deltas. rowsUpdated: anyOf: - type: string - type: 'null' title: Rowsupdated description: >- Rows whose values changed, when the ingestion mode computes semantic deltas. rowsDeleted: anyOf: - type: string - type: 'null' title: Rowsdeleted description: Rows removed, when the ingestion mode computes semantic deltas. rowsSkipped: anyOf: - type: string - type: 'null' title: Rowsskipped description: Rows skipped during ingestion. tableId: anyOf: - type: string - type: 'null' title: Tableid description: Summation table replaced by this snapshot. errorCode: anyOf: - type: string - type: 'null' title: Errorcode description: Stable public failure code. errorMessage: anyOf: - type: string - type: 'null' title: Errormessage description: Public failure guidance with internal details removed. createdAt: anyOf: - type: string - type: 'null' title: Createdat description: Snapshot creation timestamp. updatedAt: anyOf: - type: string - type: 'null' title: Updatedat description: Most recent status update timestamp. completedAt: anyOf: - type: string - type: 'null' title: Completedat description: Terminal completion timestamp. additionalProperties: false type: object required: - id - mode - status title: SnapshotPublic description: Public lifecycle and row-count state for one authoritative replacement. securitySchemes: SummationMachineAuth: type: oauth2 flows: clientCredentials: scopes: agent:read: agent:read agent:write: agent:write tokenUrl: /v1/auth/m2m/token ````