{
  "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"
      }
    }
  }
}