> ## 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 a template from an envelope

> Supports the optional Idempotency-Key header. Repeating the same key and request replays the original 201 response; a key currently in flight returns 409, and reusing a key with a different request returns 422.



## OpenAPI

````yaml /openapi.json post /api/v1/templates
openapi: 3.0.0
info:
  title: Atlas API
  version: 0.0.0
servers:
  - url: https://api.atlaswork.ai
security: []
paths:
  /api/v1/templates:
    post:
      tags:
        - Templates
      summary: Create a template from an envelope
      description: >-
        Supports the optional Idempotency-Key header. Repeating the same key and
        request replays the original 201 response; a key currently in flight
        returns 409, and reusing a key with a different request returns 422.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                sourceEnvelopeId:
                  type: string
                  minLength: 1
                name:
                  type: string
                  minLength: 1
                roles:
                  type: array
                  items:
                    type: object
                    properties:
                      participantId:
                        type: string
                        minLength: 1
                      partyIndex:
                        type: integer
                        minimum: 0
                      name:
                        type: string
                        minLength: 1
                      isSender:
                        type: boolean
                      optional:
                        type: boolean
                    required:
                      - name
                lockedFieldIds:
                  type: array
                  items:
                    type: string
              required:
                - sourceEnvelopeId
                - name
      responses:
        '201':
          description: Template graph created
          content:
            application/json:
              schema:
                type: object
                properties:
                  template:
                    type: object
                    properties:
                      id:
                        type: string
                      organizationId:
                        type: string
                      teamId:
                        type: string
                      name:
                        type: string
                      originalFilename:
                        type: string
                      sourceFormat:
                        type: string
                      contentHash:
                        type: string
                      sizeBytes:
                        type: number
                      archivedAt:
                        type: string
                        nullable: true
                        format: date-time
                      useCount:
                        type: integer
                        minimum: 0
                      lastUsedAt:
                        type: string
                        nullable: true
                        format: date-time
                      createdAt:
                        type: string
                        format: date-time
                      updatedAt:
                        type: string
                        format: date-time
                    required:
                      - id
                      - organizationId
                      - teamId
                      - name
                      - originalFilename
                      - sourceFormat
                      - contentHash
                      - sizeBytes
                      - archivedAt
                      - useCount
                      - lastUsedAt
                      - createdAt
                      - updatedAt
                  roles:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        templateId:
                          type: string
                        name:
                          type: string
                        apiRoleName:
                          type: string
                        orderIndex:
                          type: integer
                          minimum: 0
                        isSender:
                          type: boolean
                        optional:
                          type: boolean
                      required:
                        - id
                        - templateId
                        - name
                        - apiRoleName
                        - orderIndex
                        - isSender
                        - optional
                  fields:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        templateId:
                          type: string
                        roleId:
                          type: string
                        type:
                          type: string
                          enum:
                            - signature
                            - initials
                            - date
                            - text
                            - checkbox
                        page:
                          type: integer
                          minimum: 1
                        x:
                          type: number
                        'y':
                          type: number
                        width:
                          type: number
                        height:
                          type: number
                        label:
                          type: string
                          nullable: true
                        required:
                          type: boolean
                        prefillValue:
                          type: string
                          nullable: true
                        autoSource:
                          type: string
                          nullable: true
                          enum:
                            - signed_date
                            - participant_name
                            - participant_email
                            - participant_company
                            - participant_title
                            - sender_org_name
                            - null
                        prefillKey:
                          type: string
                          nullable: true
                        locked:
                          type: boolean
                      required:
                        - id
                        - templateId
                        - roleId
                        - type
                        - page
                        - x
                        - 'y'
                        - width
                        - height
                        - label
                        - required
                        - prefillValue
                        - autoSource
                        - prefillKey
                        - locked
                required:
                  - template
                  - roles
                  - fields
        '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
        '404':
          description: Source envelope not found in this organization
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  details:
                    type: object
                    additionalProperties:
                      nullable: true
                required:
                  - code
                  - message
        '409':
          description: An idempotent request with this key is already in flight
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                  message:
                    type: string
                  details:
                    type: object
                    additionalProperties:
                      nullable: true
                required:
                  - code
                  - message
        '422':
          description: Source envelope or role overrides are not valid for a template
          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 copy failed
          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.

````