openapi: 3.2.0
info:
  title: Luminance Public API v2 Document Templates API
  version: '1.5'
  description: "Luminance offers a RESTful HTTP-based API utilizing JSON as the primary serialization format and OAuth2 for authentication. This API is engineered to seamlessly integrate your software with the Luminance Platform, leveraging its objects and endpoints to enhance your applications.\n\nWith this API, you can create integrations that allow direct access to folders, tasks, and documents stored in Luminance. Additionally, you can track document progress through reviews or utilize machine learning capabilities via annotations and Traffic Light Analysis.\n\nThe Luminance API is designed with developers in mind, providing comprehensive documentation and robust support to ensure smooth integration. It adheres to industry standards, ensuring compatibility and security. Developers can take advantage of the API's flexibility to build custom solutions, automate workflows, and enhance overall efficiency within their applications.\n\nAPI requests are rate limited for security reasons to 100 requests every 10 minutes.\n\nThis version of the API is deployed by standard to Luminance product versions 1.43.0 onwards\n\n## Authentication (OAuth2 client credentials)\n\nTo test endpoints from this document you need an access token. Use the **Authorize** button and enter the token as described below.\n\n1. **Prerequisites**\n   Ensure you have a Client ID and Client Secret (configured as a Service User).\n\n2. **Encode credentials**\n   Base64-encode the string `<client-id>:<client-secret>`. For example:\n   `echo -n '<client-id>:<client-secret>' | base64`\n\n3. **Request a token**\n   Send a POST request to your instance token endpoint:\n   - URL: `https://<moniker>.app.luminance.com/auth/oauth2/token` (replace `<moniker>` with your instance moniker).\n   - Headers: `Content-Type: application/x-www-form-urlencoded`, `Authorization: Basic <base64_encoded_credentials>`.\n   - Body: `grant_type=client_credentials`.\n\n   Example:\n   ```\n   curl 'https://<moniker>.app.luminance.com/auth/oauth2/token' \\\n     -X POST \\\n     -H 'Content-Type: application/x-www-form-urlencoded' \\\n     -H 'Authorization: Basic <base64_encoded_credentials>' \\\n     -d 'grant_type=client_credentials'\n   ```\n\n4. **Use the token**\n   The response includes `access_token`. In this UI, click **Authorize**, choose **bearerAuth**, and paste the `access_token` value (no \"Bearer \" prefix needed). Then call any endpoint; the request will send `Authorization: Bearer <access_token>`.\n\n5. **Example API call**\n   Once authorized, use the token in the `Authorization` header for requests, e.g.:\n   `curl 'https://<moniker>.app.luminance.com/api2/<chosen-path>' -H 'Authorization: Bearer <access_token>'`\n"
servers:
- url: https://{moniker}.app.luminance.com
  description: Your Luminance instance
  variables:
    moniker:
      default: your-instance
      description: Instance moniker (e.g. acme)
security:
- bearerAuth: []
tags:
- name: Document Templates
paths:
  /api2/projects/{project_id}/document_templates:
    get:
      tags:
      - Document Templates
      summary: List document templates in project
      description: Contract/document templates for the project. Use GET .../document_templates/{id}/fields to get the schema required for contract creation.
      parameters:
      - $ref: '#/components/parameters/projectId'
      - in: query
        name: id
        schema:
          type: integer
        description: Filter by document template ID
      - in: query
        name: name
        schema:
          type: string
      - in: query
        name: default_folder_id
        schema:
          type: integer
        description: Folder ID where documents created from this template are saved
      - in: query
        name: state
        schema:
          type: string
        description: active or deleted
      - in: query
        name: media_type
        schema:
          type: string
        description: Media type (e.g. MS Word MIME type)
      - in: query
        name: limit
        schema:
          type: integer
          minimum: 1
      - in: query
        name: offset
        schema:
          type: integer
          minimum: 0
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/DocumentTemplate'
              example:
              - id: 1
                created_at: '2024-01-15T12:00:00.000Z'
                created_by: 1
                name: Joe Bloggs
                project_id: 1
                default_folder_id: 1
                media_type: application/pdf
                state: active
                options: {}
  /api2/projects/{project_id}/document_templates/{document_template_id}:
    get:
      tags:
      - Document Templates
      summary: Get document template by id
      parameters:
      - $ref: '#/components/parameters/projectId'
      - in: path
        name: document_template_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DocumentTemplate'
              example:
                id: 1
                created_at: '2024-01-15T12:00:00.000Z'
                created_by: 1
                name: Joe Bloggs
                project_id: 1
                default_folder_id: 1
                media_type: application/pdf
                state: active
                options: {}
        '404':
          description: Not found
  /api2/projects/{project_id}/document_templates/{document_template_id}/fields:
    get:
      tags:
      - Document Templates
      summary: Get document template fields (for contract creation)
      parameters:
      - $ref: '#/components/parameters/projectId'
      - in: path
        name: document_template_id
        required: true
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
              example:
                id: 1
                created_at: '2024-01-15T12:00:00.000Z'
                created_by: 1
                name: Joe Bloggs
                key: example_key
                field_order: 0
                document_template_id: 1
                parent_data_field_id: 1
                datatype: string
                options: {}
                type: document
                conditions: {}
  /api2/projects/{project_id}/document_templates/create:
    post:
      tags:
      - Document Templates
      summary: Create contract (matter + generated document from template)
      description: Get template fields from GET .../document_templates/{id}/fields; the data object keys match field keys (e.g. singleInputFieldKey for type datatag). For nested/loop fields use arrays of objects. See docuvault Contract Creation and Postman Contract Generation collection.
      parameters:
      - $ref: '#/components/parameters/projectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DocumentTemplateCreateRequest'
      responses:
        '201':
          description: Created
        '422':
          description: Validation error
components:
  schemas:
    DocumentTemplate:
      type: object
      description: Document template for contract generation (see API2_Schema document_templates table)
      properties:
        id:
          type: integer
        created_at:
          type: string
          format: date-time
        created_by:
          type: integer
        name:
          type: string
        project_id:
          type: integer
        default_folder_id:
          type: integer
        media_type:
          type: string
        state:
          type: string
        options:
          type: object
    DocumentTemplateCreateRequest:
      type: object
      description: Payload for POST document_templates/create (contract creation). Get field keys from GET .../document_templates/{id}/fields; pass values in data keyed by field keys (e.g. singleInputFieldKey from fields of type datatag).
      properties:
        document_template_id:
          type: integer
        data:
          type: object
          description: Key-value map of template field keys to values
        name:
          type: string
        state:
          type: string
        workflow_id:
          type: integer
      required:
      - document_template_id
      - data
  parameters:
    projectId:
      in: path
      name: project_id
      required: true
      schema:
        type: integer
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: 'Access token from the OAuth2 client credentials flow. See the Authentication section above for how to obtain a token (curl to your instance token endpoint); then paste the access_token here.

        '