superdocs-app Templates API

openapi: 3.2.0
info:
  title: 'Typebar API: Universal Document AI Templates API'
  description: 'Typebar (formerly SuperDocs): AI-powered document editing with multi-tenant organization support'
  version: 2.0.0
servers:
- url: https://api.superdocs.app
tags:
- name: Templates
paths:
  /v1/templates/upload-base64:
    post:
      tags:
      - Templates
      summary: Save a document template (NDA, contract, SOP, letterhead) for reuse across…
      description: 'Templates persist across sessions and can be referenced by the AI when drafting new documents (e.g., "draft an NDA using my standard template"). Stored at user or organization scope. Ideal for boilerplate, branded letterheads, recurring document structures, or compliance-required templates. Supports the same formats as document upload: .docx, .pdf, .txt, .rtf, .md, .html, .htm, .tex. Max 50 MB validated; note the hosted transport layer caps any REQUEST BODY at ~32 MB and rejects larger ones at the gateway with an HTML (not JSON) error — base64 inflates content ~33%, so inline uploads are reliable up to ~20 MB of file bytes; beyond that use request_upload_url (pre-signed flow, up to 100 MB).'
      operationId: upload_template_base64
      security:
      - HTTPBearer: []
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Base64UploadRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/templates/upload:
    post:
      tags:
      - Templates
      summary: Upload User Template
      description: 'Upload a document file as a personal/organization template.


        The file is processed synchronously: text extraction, HTML conversion, and content indexing.

        Supported formats: .docx, .pdf, .txt, .rtf, .md, .html, .htm, .tex

        Templates are scoped to the uploading user or organization.'
      operationId: upload_user_template
      security:
      - HTTPBearer: []
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/Body_upload_user_template'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/templates:
    get:
      tags:
      - Templates
      summary: List all saved document templates available to the user or organization
      description: 'Returns active (non-deleted) templates with name, format, size, and creation date metadata. Use to show the AI what reusable document structures are available for drafting new documents. Templates are scoped to the authenticated entity: users via the web app or sk_ key see only their own templates; organizations via lce_ key see theirs.'
      operationId: list_user_templates
      security:
      - HTTPBearer: []
      parameters:
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/templates/{template_id}:
    delete:
      tags:
      - Templates
      summary: Delete a saved document template by ID
      description: Soft-deletes the template; only the owner (user or organization) can delete. Once deleted, the template no longer appears in list_user_templates and cannot be referenced by the AI for new documents. Existing documents already drafted from the template are unaffected.
      operationId: delete_user_template
      security:
      - HTTPBearer: []
      parameters:
      - name: template_id
        in: path
        required: true
        schema:
          type: string
          title: Template Id
      - name: authorization
        in: header
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Authorization
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema: {}
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    Body_upload_user_template:
      properties:
        file:
          type: string
          format: binary
          title: File
      type: object
      required:
      - file
      title: Body_upload_user_template
    Base64UploadRequest:
      properties:
        filename:
          type: string
          maxLength: 512
          title: Filename
          description: Original filename with extension (e.g. 'contract.pdf'). Used for file type detection.
        file_base64:
          type: string
          maxLength: 50000000
          title: File Base64
          description: Base64-encoded file content.
        session_id:
          anyOf:
          - type: string
            maxLength: 256
          - type: 'null'
          title: Session Id
          description: Session ID. Auto-generated if not provided.
        return_html:
          type: boolean
          title: Return Html
          description: 'With a session_id: false (default) returns compact metadata only (chunks_count, version_id, page_setup) — the document is loaded into the session and you edit it via chat, keeping your context small; true returns the full parsed HTML inline. Ignored on the convert-only path (no session_id), which always returns the converted html.'
          default: false
      type: object
      required:
      - filename
      - file_base64
      title: Base64UploadRequest
      description: JSON request body for base64-encoded file uploads.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    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
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer