> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beta.adapter.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Write agent output back into the workspace

<Snippet file="api/writeback/write-back.mdx" />


## OpenAPI

````yaml POST /v1/writeback
openapi: 3.1.0
info:
  title: Adapter API
  description: Connect and sync data from any SaaS tool.
  version: 0.1.0
servers:
  - url: https://api.adapter.com
security:
  - ApiKeyAuth: []
tags:
  - name: connections
    description: Manage OAuth connections to data sources.
paths:
  /v1/writeback:
    post:
      tags:
        - writeback
      summary: Write agent output back into the workspace
      operationId: write_back
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WritebackRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WritebackResponse'
        '402':
          description: >-
            Ingest fully rejected — the workspace is over a tier quota
            (documents / storage / per-document size). Partial batches instead
            return 200 with a `rejected` list. Not transient; upgrade or free
            space rather than retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QuotaExceededErrorModel'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    WritebackRequest:
      properties:
        items:
          items:
            $ref: '#/components/schemas/WritebackItem'
          type: array
          maxItems: 100
          minItems: 1
          title: Items
        agent:
          anyOf:
            - type: string
              maxLength: 60
            - type: 'null'
          title: Agent
          description: >-
            Name of the agent doing the writing (e.g. 'sales-research-bot').
            Becomes the connector the items land under (custom:mcp-<agent>).
            Omit for OAuth MCP clients — their client type is used.
        force:
          type: boolean
          title: Force
          description: Re-publish items whose content is unchanged.
          default: false
      type: object
      required:
        - items
      title: WritebackRequest
    WritebackResponse:
      properties:
        connector_id:
          type: string
          title: Connector Id
        source:
          type: string
          title: Source
        agent:
          type: string
          title: Agent
        items:
          items:
            $ref: '#/components/schemas/WritebackResultItem'
          type: array
          title: Items
      type: object
      required:
        - connector_id
        - source
        - agent
        - items
      title: WritebackResponse
    QuotaExceededErrorModel:
      properties:
        error_code:
          type: string
          const: quota_exceeded
          title: Error Code
          default: quota_exceeded
        message:
          type: string
          title: Message
          default: 'Ingest rejected: this workspace is over its plan quota.'
        details:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Details
          description: >-
            Carries `rejected`: the refused items as `{external_id, resource,
            reason}` (resource ∈ documents/storage/doc_size).
      type: object
      title: QuotaExceededErrorModel
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    WritebackItem:
      properties:
        kind:
          type: string
          enum:
            - note
            - decision
            - summary
            - task_outcome
            - fact
            - document
          title: Kind
          description: What this is; see KIND_GUIDE / the tool docs.
          examples:
            - decision
        title:
          type: string
          maxLength: 300
          minLength: 1
          title: Title
          description: Short, specific headline.
        content:
          type: string
          maxLength: 200000
          minLength: 1
          title: Content
          description: The body. Markdown is fine.
        external_id:
          anyOf:
            - type: string
              maxLength: 200
            - type: 'null'
          title: External Id
          description: >-
            Stable id to update the same item later. Omit for a new item (one is
            minted).
        timestamp:
          anyOf:
            - type: string
              format: date-time
            - type: 'null'
          title: Timestamp
          description: When it happened (ISO 8601). Defaults to now.
        related_urns:
          items:
            type: string
          type: array
          maxItems: 50
          title: Related Urns
          description: >-
            Adapter urns this was derived from (search_knowledge hits, trigger
            deliveries).
        tags:
          items:
            type: string
          type: array
          maxItems: 20
          title: Tags
          description: Free-form labels.
        metadata:
          anyOf:
            - additionalProperties:
                type: string
              type: object
            - type: 'null'
          title: Metadata
          description: Extra string key/values for filtering.
      type: object
      required:
        - kind
        - title
        - content
      title: WritebackItem
    WritebackResultItem:
      properties:
        external_id:
          type: string
          title: External Id
        status:
          type: string
          enum:
            - saved
            - unchanged
            - rejected
          title: Status
        reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Reason
      type: object
      required:
        - external_id
        - status
      title: WritebackResultItem
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      description: Pass your `pk_live_...` API key as a Bearer token.

````