openapi: 3.0.1
info:
  title: CATMA JSON API
  description: "For more information see the [JSON API](https://catma.de/documentation/access-your-project-data/json-api/)\
    \ page on our website."
  termsOfService: https://catma.de/documentation/terms-of-use/
  contact:
    email: support@catma.de
  version: "1.0"
servers:
- url: ./
  description: the server hosting the API definition
- url: https://app.catma.de/api/v1
  description: public CATMA server
tags:
- name: Authentication
  description: Authenticate with the API
- name: Projects
  description: List the projects you have access to
- name: Project Export
  description: Export project resources in an easy-to-use JSON format
paths:
  /auth:
    post:
      tags:
      - Authentication
      description: "Authenticate using one of: 'Authorization' header ('Basic' or\
        \ 'Bearer' schemes), 'access_token' form parameter, or 'username' and 'password'\
        \ form parameters. The options should be viewed as mutually exclusive. The\
        \ form parameters are merely an alternative to using the 'Authorization' header\
        \ with the corresponding scheme. Returns a JWT that should be used to authenticate\
        \ requests to any of the other, non-authentication endpoints (which only accept\
        \ bearer authentication). Note that you won't be able to test the header option\
        \ in Swagger UI."
      operationId: authenticate
      parameters:
      - name: Authorization
        in: header
        schema:
          type: string
      requestBody:
        description: "Optional form parameters, partially required if no 'Authorization'\
          \ header is supplied. Send either a CATMA access token or your username\
          \ and password."
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              properties:
                access_token:
                  type: string
                username:
                  type: string
                password:
                  type: string
      responses:
        "200":
          description: A JSON Web Token
        "400":
          description: Missing or malformed header or parameters
        "401":
          description: Invalid credentials
  /auth/google:
    get:
      tags:
      - Authentication
      description: "Authenticate with your Google account. Only use this if you log\
        \ in to CATMA using the 'Sign in with Google' option. A browser is required\
        \ to complete the OAuth flow. Redirects to Google and, if successfully authenticated,\
        \ responds in the same way as the /auth endpoint. Note that you won't be able\
        \ to test this in Swagger UI (but you can easily visit the URL in a separate\
        \ tab to try it out)."
      operationId: googleOauth
      responses:
        "307":
          description: Redirect to Google login
  /projects/{namespace}/{projectId}/export:
    get:
      tags:
      - Project Export
      description: "Namespace is a username, as projects are always owned by a particular\
        \ user. Use the projects endpoint to list available projects with their namespace\
        \ and ID. Output is paginated and 'pageSize' defaults to 100 (the no. of annotations\
        \ returned per page). Links to previous and next pages are also returned.\
        \ Extended metadata is only returned with the first page by default, unless\
        \ specified with 'includeExtendedMetadata'. Use 'forcePull' to force the server\
        \ to update its copy of the project."
      operationId: getProjectExport
      parameters:
      - name: namespace
        in: path
        required: true
        schema:
          type: string
      - name: projectId
        in: path
        required: true
        schema:
          type: string
      - name: includeExtendedMetadata
        in: query
        schema:
          type: boolean
      - name: page
        in: query
        schema:
          type: integer
          format: int32
      - name: pageSize
        in: query
        schema:
          type: integer
          format: int32
      - name: forcePull
        in: query
        schema:
          type: boolean
      responses:
        "200":
          description: "Note that where you see 'additionalPropN' keys in the sample\
            \ output, this would actually be a resource ID in most cases, allowing\
            \ for direct lookups by ID in the 'extendedMetadata'. Tag properties are\
            \ the exception and are not accurately represented here. See the link\
            \ to our website at the top of the page for an accurate example."
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ProjectExport"
        "404":
          description: Project not found
      security:
      - BearerAuth: []
  /projects/{namespace}/{projectId}/export/doc/{documentId}:
    get:
      tags:
      - Project Export
      description: Returns the content of the specified document. Note that document
        URLs are returned as part of the 'extendedMetadata' of the project export
        endpoint.
      operationId: getProjectExportDocument
      parameters:
      - name: namespace
        in: path
        required: true
        schema:
          type: string
      - name: projectId
        in: path
        required: true
        schema:
          type: string
      - name: documentId
        in: path
        required: true
        schema:
          type: string
      responses:
        "200":
          description: The document content as UTF-8 plain text
        "404":
          description: Project or document not found
      security:
      - BearerAuth: []
  /projects:
    get:
      tags:
      - Projects
      operationId: getProjects
      responses:
        "200":
          description: Project list
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ProjectReference"
      security:
      - BearerAuth: []
components:
  schemas:
    ProjectExport:
      type: object
      properties:
        exportId:
          type: string
        exportCreatedAt:
          type: string
          format: date-time
        totalPages:
          type: integer
          format: int32
        pageNo:
          type: integer
          format: int32
        pageSize:
          type: integer
          format: int32
        prevPage:
          type: string
        nextPage:
          type: string
        extendedMetadata:
          $ref: "#/components/schemas/ProjectExportExtendedMetadata"
        documents:
          type: array
          items:
            $ref: "#/components/schemas/ProjectExportDocument"
    ProjectExportAnnotatedPhrase:
      type: object
      properties:
        startOffset:
          type: integer
          format: int32
        endOffset:
          type: integer
          format: int32
        phrase:
          type: string
    ProjectExportAnnotation:
      type: object
      properties:
        id:
          type: string
        phrases:
          type: array
          items:
            $ref: "#/components/schemas/ProjectExportAnnotatedPhrase"
        annotationCollectionId:
          type: string
        annotationCollectionName:
          type: string
        tagId:
          type: string
        tagName:
          type: string
        tagColor:
          type: string
        tagPath:
          type: string
        author:
          type: string
        createdAt:
          type: string
          format: date-time
        userProperties:
          type: array
          items:
            $ref: "#/components/schemas/ProjectExportAnnotationProperty"
    ProjectExportAnnotationCollection:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        author:
          type: string
        description:
          type: string
        publisher:
          type: string
        responsibleUser:
          type: string
        documentId:
          type: string
    ProjectExportAnnotationProperty:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        values:
          type: array
          items:
            type: string
    ProjectExportDocument:
      type: object
      properties:
        id:
          type: string
        title:
          type: string
        annotations:
          type: array
          items:
            $ref: "#/components/schemas/ProjectExportAnnotation"
    ProjectExportExtendedMetadata:
      type: object
      properties:
        documents:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/ProjectExportSourceDocument"
        annotationCollections:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/ProjectExportAnnotationCollection"
        tagsets:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/ProjectExportTagsetDefinition"
        tags:
          type: object
          additionalProperties:
            $ref: "#/components/schemas/ProjectExportTagDefinition"
    ProjectExportSourceDocument:
      type: object
      properties:
        id:
          type: string
        bodyUrl:
          type: string
        crc32bChecksum:
          type: string
        size:
          type: integer
          format: int32
        title:
          type: string
        author:
          type: string
        description:
          type: string
        publisher:
          type: string
        responsibleUser:
          type: string
    ProjectExportTagDefinition:
      type: object
      properties:
        id:
          type: string
        parentId:
          type: string
        name:
          type: string
        properties:
          type: object
          additionalProperties:
            type: object
        tagsetId:
          type: string
    ProjectExportTagsetDefinition:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        responsibleUser:
          type: string
    ProjectReference:
      type: object
      properties:
        namespace:
          type: string
        name:
          type: string
        description:
          type: string
        createdAt:
          type: string
          format: date-time
        lastActivityAt:
          type: string
          format: date-time
        id:
          type: string
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
