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

# Create an envelope

> Creates a draft envelope with its participant and field graph. The document arrives by public URL, inline base64 content, chat-authored text rendered to PDF, a same-organization envelope document, or deferred upload (`{ upload: true }` returns a short-lived signed `uploadUrl`; it is never re-issued after create). Returns immediately with the envelope, a review URL for the web review page, a human/agent-readable `note` describing the next step, and never blocks on field detection. URL and inline documents enqueue field detection asynchronously after the document is stored (the envelope moves draft → detecting → review); deferred-upload envelopes skip detection and remain sendable with manually placed fields. Supports the `Idempotency-Key` header: a replayed completed key returns the envelope's current graph with the original status code and `Idempotency-Replayed: true` (never re-executing); an in-flight duplicate is rejected 409; reusing a key with a different request is rejected 422. A replayed create re-mints the review URL but never the one-shot upload URL.



## OpenAPI

````yaml /openapi.json post /api/v1/envelopes
openapi: 3.0.0
info:
  title: Atlas API
  version: 0.0.0
servers:
  - url: https://api.atlaswork.ai
security: []
paths:
  /api/v1/envelopes:
    post:
      tags:
        - envelopes
      summary: Create an envelope
      description: >-
        Creates a draft envelope with its participant and field graph. The
        document arrives by public URL, inline base64 content, chat-authored
        text rendered to PDF, a same-organization envelope document, or deferred
        upload (`{ upload: true }` returns a short-lived signed `uploadUrl`; it
        is never re-issued after create). Returns immediately with the envelope,
        a review URL for the web review page, a human/agent-readable `note`
        describing the next step, and never blocks on field detection. URL and
        inline documents enqueue field detection asynchronously after the
        document is stored (the envelope moves draft → detecting → review);
        deferred-upload envelopes skip detection and remain sendable with
        manually placed fields. Supports the `Idempotency-Key` header: a
        replayed completed key returns the envelope's current graph with the
        original status code and `Idempotency-Replayed: true` (never
        re-executing); an in-flight duplicate is rejected 409; reusing a key
        with a different request is rejected 422. A replayed create re-mints the
        review URL but never the one-shot upload URL.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                document:
                  anyOf:
                    - type: object
                      properties:
                        url:
                          type: string
                          format: uri
                        filename:
                          type: string
                          minLength: 1
                      required:
                        - url
                    - type: object
                      properties:
                        contentBase64:
                          type: string
                          minLength: 1
                        filename:
                          type: string
                          minLength: 1
                      required:
                        - contentBase64
                        - filename
                    - type: object
                      properties:
                        text:
                          type: string
                          minLength: 1
                        filename:
                          type: string
                          minLength: 1
                      required:
                        - text
                    - type: object
                      properties:
                        envelopeId:
                          type: string
                          format: uuid
                      required:
                        - envelopeId
                    - type: object
                      properties:
                        upload:
                          type: boolean
                          enum:
                            - true
                        filename:
                          type: string
                          minLength: 1
                      required:
                        - upload
                        - filename
                participants:
                  type: array
                  items:
                    type: object
                    properties:
                      name:
                        type: string
                        minLength: 1
                      email:
                        type: string
                        format: email
                      company:
                        type: string
                        nullable: true
                        maxLength: 200
                      title:
                        type: string
                        nullable: true
                        maxLength: 200
                      detectedPartyIndex:
                        type: integer
                        nullable: true
                        minimum: 0
                    required:
                      - name
                      - email
                fields:
                  type: array
                  items:
                    type: object
                    properties:
                      participantIndex:
                        type: integer
                        minimum: 0
                      partyIndex:
                        type: integer
                        minimum: 0
                      type:
                        type: string
                        enum:
                          - signature
                          - initials
                          - date
                          - text
                          - checkbox
                      page:
                        type: integer
                        minimum: 1
                      x:
                        type: number
                        minimum: 0
                        maximum: 1
                      'y':
                        type: number
                        minimum: 0
                        maximum: 1
                      width:
                        type: number
                        minimum: 0
                        maximum: 1
                      height:
                        type: number
                        minimum: 0
                        maximum: 1
                      label:
                        type: string
                        nullable: true
                      required:
                        type: boolean
                      prefillValue:
                        type: string
                        nullable: true
                        description: >-
                          Static sender-supplied value for text or date fields.
                          Ignored on checkbox fields, which always remain
                          signer-controlled.
                      autoSource:
                        type: string
                        nullable: true
                        enum:
                          - signed_date
                          - participant_name
                          - participant_email
                          - participant_company
                          - participant_title
                          - sender_org_name
                          - null
                        description: >-
                          Derive this field's value server-side when the signer
                          signs: signed_date (date fields) or participant_name /
                          participant_email / participant_company /
                          participant_title / sender_org_name (text fields).
                          Mutually exclusive with prefillValue. The resolved
                          value is recorded in the envelope's audit trail.
                      proposedAutoSource:
                        type: string
                        nullable: true
                        enum:
                          - signed_date
                          - participant_name
                          - participant_email
                          - participant_company
                          - participant_title
                          - sender_org_name
                          - null
                        description: >-
                          Detection-proposal echo. On draft updates, echo the
                          proposedAutoSource you read to keep the suggestion;
                          omitting or nulling it dismisses it. Cannot introduce
                          or change a proposal (detection is the only origin);
                          ignored at envelope create.
                      source:
                        type: string
                        enum:
                          - detected
                          - manual
                          - template
                    required:
                      - type
                      - page
                      - x
                      - 'y'
                      - width
                      - height
                displayName:
                  type: string
                  minLength: 1
                  maxLength: 255
                policy:
                  type: object
                  properties:
                    deliveryMode:
                      type: string
                      enum:
                        - review_first
                        - auto_send
                    legalFramework:
                      type: string
                      nullable: true
                    consumerDisclosure:
                      type: boolean
                    expiresAt:
                      type: string
                      format: date-time
                    reminderPolicy:
                      nullable: true
                metadata:
                  nullable: true
              required:
                - document
                - participants
                - fields
      responses:
        '201':
          description: Envelope created (status draft, version 1)
          content:
            application/json:
              schema:
                type: object
                properties:
                  envelope:
                    type: object
                    properties:
                      envelope:
                        type: object
                        properties:
                          id:
                            type: string
                          organizationId:
                            type: string
                          teamId:
                            type: string
                          templateId:
                            type: string
                            nullable: true
                          templateContentHash:
                            type: string
                            nullable: true
                          status:
                            type: string
                            enum:
                              - draft
                              - detecting
                              - review
                              - in_progress
                              - completed
                              - declined
                              - voided
                              - expired
                          detectionStatus:
                            type: string
                            enum:
                              - none
                              - running
                              - succeeded
                              - failed
                          version:
                            type: integer
                          originalFilename:
                            type: string
                            nullable: true
                          displayName:
                            type: string
                            nullable: true
                          sourceFormat:
                            type: string
                            nullable: true
                          contentHash:
                            type: string
                            nullable: true
                          sizeBytes:
                            type: number
                            nullable: true
                          deliveryMode:
                            type: string
                          legalFramework:
                            type: string
                            nullable: true
                          consumerDisclosure:
                            type: boolean
                          expiresAt:
                            type: string
                            nullable: true
                            format: date-time
                          scheduledSendAt:
                            type: string
                            nullable: true
                            format: date-time
                          reminderPolicy:
                            nullable: true
                          sentAt:
                            type: string
                            nullable: true
                            format: date-time
                          completedAt:
                            type: string
                            nullable: true
                            format: date-time
                          declinedAt:
                            type: string
                            nullable: true
                            format: date-time
                          voidedAt:
                            type: string
                            nullable: true
                            format: date-time
                          expiredAt:
                            type: string
                            nullable: true
                            format: date-time
                          metadata:
                            nullable: true
                          senderUserId:
                            type: string
                            nullable: true
                          senderName:
                            type: string
                            nullable: true
                          senderEmail:
                            type: string
                            nullable: true
                          detectedParties:
                            nullable: true
                          createdAt:
                            type: string
                            format: date-time
                          updatedAt:
                            type: string
                            format: date-time
                        required:
                          - id
                          - organizationId
                          - teamId
                          - templateId
                          - templateContentHash
                          - status
                          - detectionStatus
                          - version
                          - originalFilename
                          - displayName
                          - sourceFormat
                          - contentHash
                          - sizeBytes
                          - deliveryMode
                          - legalFramework
                          - consumerDisclosure
                          - expiresAt
                          - scheduledSendAt
                          - sentAt
                          - completedAt
                          - declinedAt
                          - voidedAt
                          - expiredAt
                          - createdAt
                          - updatedAt
                      participants:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                            envelopeId:
                              type: string
                            organizationId:
                              type: string
                            orderIndex:
                              type: integer
                            name:
                              type: string
                            email:
                              type: string
                            company:
                              type: string
                              nullable: true
                            title:
                              type: string
                              nullable: true
                            status:
                              type: string
                              enum:
                                - pending
                                - signed
                                - declined
                            detectedPartyIndex:
                              type: integer
                              nullable: true
                            consentedAt:
                              type: string
                              nullable: true
                              format: date-time
                            signedAt:
                              type: string
                              nullable: true
                              format: date-time
                            declinedAt:
                              type: string
                              nullable: true
                              format: date-time
                            declineReason:
                              type: string
                              nullable: true
                            lastViewedAt:
                              type: string
                              nullable: true
                              format: date-time
                            lastIpAddress:
                              type: string
                              nullable: true
                            lastUserAgent:
                              type: string
                              nullable: true
                            createdAt:
                              type: string
                              format: date-time
                            updatedAt:
                              type: string
                              format: date-time
                          required:
                            - id
                            - envelopeId
                            - organizationId
                            - orderIndex
                            - name
                            - email
                            - status
                            - consentedAt
                            - signedAt
                            - declinedAt
                            - declineReason
                            - lastViewedAt
                            - lastIpAddress
                            - lastUserAgent
                            - createdAt
                            - updatedAt
                      fields:
                        type: array
                        items:
                          type: object
                          properties:
                            id:
                              type: string
                            envelopeId:
                              type: string
                            organizationId:
                              type: string
                            participantId:
                              type: string
                              nullable: true
                            partyIndex:
                              type: integer
                              nullable: true
                            type:
                              type: string
                              enum:
                                - signature
                                - initials
                                - date
                                - text
                                - checkbox
                            page:
                              type: integer
                            x:
                              type: number
                            'y':
                              type: number
                            width:
                              type: number
                            height:
                              type: number
                            label:
                              type: string
                              nullable: true
                            required:
                              type: boolean
                            source:
                              type: string
                              enum:
                                - detected
                                - manual
                                - template
                            prefillValue:
                              type: string
                              nullable: true
                            locked:
                              type: boolean
                            autoSource:
                              type: string
                              nullable: true
                              enum:
                                - signed_date
                                - participant_name
                                - participant_email
                                - participant_company
                                - participant_title
                                - sender_org_name
                                - null
                            proposedAutoSource:
                              type: string
                              nullable: true
                              enum:
                                - signed_date
                                - participant_name
                                - participant_email
                                - participant_company
                                - participant_title
                                - sender_org_name
                                - null
                            value:
                              type: string
                              nullable: true
                            filledAt:
                              type: string
                              nullable: true
                              format: date-time
                            createdAt:
                              type: string
                              format: date-time
                            updatedAt:
                              type: string
                              format: date-time
                          required:
                            - id
                            - envelopeId
                            - organizationId
                            - participantId
                            - type
                            - page
                            - x
                            - 'y'
                            - width
                            - height
                            - label
                            - required
                            - source
                            - prefillValue
                            - locked
                            - autoSource
                            - proposedAutoSource
                            - value
                            - filledAt
                            - createdAt
                            - updatedAt
                    required:
                      - envelope
                      - participants
                      - fields
                  reviewUrl:
                    type: string
                    format: uri
                  uploadUrl:
                    type: string
                    format: uri
                  note:
                    type: string
                required:
                  - envelope
                  - reviewUrl
                  - note
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  details:
                    type: object
                    additionalProperties:
                      nullable: true
                required:
                  - code
                  - message
        '413':
          description: Raw request body exceeds the pre-parse size limit
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  details:
                    type: object
                    additionalProperties:
                      nullable: true
                required:
                  - code
                  - message
        '422':
          description: >-
            Validation failed: malformed input, document intake rejected
            (private address, size cap, content type), or duplicate participant
            emails
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  details:
                    type: object
                    additionalProperties:
                      nullable: true
                required:
                  - code
                  - message
        '502':
          description: Document storage failed; the draft exists without a stored document
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  details:
                    type: object
                    additionalProperties:
                      nullable: true
                required:
                  - code
                  - message
      security:
        - apiKey: []
        - oauthJwt: []
components:
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      description: >-
        Organization API key (format `atlas_sk_...`), passed as a bearer token
        or the x-api-key header. Created and revoked in the dashboard (Better
        Auth api-key plugin); shown in full only once and stored hashed.
    oauthJwt:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: >-
        Better Auth OAuth resource access token. The token audience must match
        the Atlas MCP resource and include the scope required by the route.

````