openapi: 3.0.1 info: title: TerminusDB API description: API for TerminusDB contact: email: team@terminusdb.com license: name: Apache 2.0 url: http://www.apache.org/licenses/LICENSE-2.0.html version: 10.0.3 externalDocs: description: Find out more about TerminusDB url: https://terminusdb.com/docs/ servers: - url: http://localhost:6363/api/ security: - basicAuth: [] tags: - name: TerminusDB description: Everything about TerminusDB externalDocs: description: Find out more url: https://terminusdb.com # TODO: Some paths are not covered yet: # - a lot of the git-like features paths: /: get: tags: - connection summary: Get a list of databases for the authenticated user responses: 200: description: successful operation content: application/json: schema: type: array items: $ref: '#/components/schemas/Database' 401: $ref: '#/components/responses/UnauthorizedError' /info: get: tags: - connection summary: Get information about the TerminusDB version responses: 200: description: succesful operation content: application/json: schema: type: object properties: "@type": type: string example: api:InfoResponse "api:info": type: object properties: "authority": type: string example: "terminusdb://system/data/User/admin" "storage": type: object properties: "version": type: string example: "1" "terminusdb": type: object properties: "version": type: string example: "10.0.13" "terminusdb_store": type: object properties: "version": type: string example: "0.19.5" "api:status": type: string example: api:success /ok: get: tags: - connection summary: Simple status update responses: 200: description: Succeeded /db/: get: tags: - database summary: List details of all databases available to the authorized user. parameters: - name: branches in: query description: Return branches or not required: false schema: type: boolean default: false - name: verbose in: query description: Return all available information required: false schema: type: boolean default: false responses: 200: description: Database listing content: application/json: schema: $ref: '#/components/schemas/Database' 404: description: database not found content: application/json: schema: type: object /db/{organization}/{database}: get: tags: - database summary: List details of the database under the given organization. parameters: - $ref: '#/components/parameters/organization' - $ref: '#/components/parameters/database' - name: branches in: query description: Return branches or not required: false schema: type: boolean default: false - name: verbose in: query description: Return all available information required: false schema: type: boolean default: false responses: 200: description: Database listing content: application/json: schema: type: array items: $ref: '#/components/schemas/Database' 404: description: Database not found content: application/json: schema: type: object head: tags: - database summary: Check that a db exists parameters: - $ref: '#/components/parameters/organization' - $ref: '#/components/parameters/database' responses: 200: description: Database exists content: application/json: schema: type: object 404: description: Database not found content: application/json: schema: type: object post: tags: - database summary: Create a database parameters: - $ref: '#/components/parameters/organization' - $ref: '#/components/parameters/database' requestBody: # TODO: Missing prefixes required: true content: application/json: schema: type: object properties: comment: type: string example: A sample comment for my database label: type: string example: Testdatabase public: type: boolean example: false description: Should the database be accessible for all users? schema: type: boolean example: true description: Should the database be initialized with a schema? required: - comment - label responses: 200: description: Added database content: application/json: schema: type: object properties: "@type": type: string example: api:DbCreateResponse "api:status": type: string example: api:success 400: description: Database already exists content: application/json: schema: type: object properties: "@type": type: string example: api:DbCreateErrorResponse "api:error": type: object properties: "@type": type: string example: api:DatabaseAlreadyExists "api:database_name": type: string example: MyNewAlreadyExistingDatabase "api:organization_name": type: string example: admin "api:message": type: string example: Database already exists. "api:status": type: string example: api:failure 401: $ref: '#/components/responses/UnauthorizedError' delete: tags: - database summary: Delete a database parameters: - $ref: '#/components/parameters/organization' - $ref: '#/components/parameters/database' - name: force in: query description: Force database to be delete (useful for databases in inconsistent states) required: false schema: type: boolean default: false responses: 200: description: Succesfully deleted DB content: application/json: schema: type: object properties: "@type": type: string example: api:DbDeleteResponse "api:status": type: string example: api:success 403: description: Forbidden 404: description: Can't find DB content: application/json: schema: type: object properties: "@type": type: string example: api:DbDeleteErrorResponse "api:error": type: object properties: "@type": type: string example: api:UnknownDatabase "api:database_name": type: string example: MyNonExistingDatabase "api:organization_name": type: string example: admin put: tags: - database summary: Change qualities of a database (label, comment, etc.) parameters: - $ref: '#/components/parameters/organization' - $ref: '#/components/parameters/database' requestBody: # TODO: Missing prefixes required: true content: application/json: schema: type: object properties: comment: type: string example: A sample comment for my database label: type: string example: Testdatabase public: type: boolean example: false description: Should the database be accessible for all users? schema: type: boolean example: true description: Should the database be initialized with a schema? required: - comment - label responses: 200: description: Updated database content: application/json: schema: type: object properties: "@type": type: string example: api:DbUpdatedResponse "api:status": type: string example: api:success 404: description: Database not found content: application/json: schema: type: object properties: "@type": type: string example: api:DbUpdateErrorResponse "api:error": type: object properties: "@type": type: string example: api:UnknownDatabase "api:database_name": type: string example: MyNonExistingDatabase "api:organization_name": type: string example: admin "api:message": type: string example: "Unknown database: admin/MyNonExistingDatabase" "api:status": type: string example: api:not_found 401: $ref: '#/components/responses/UnauthorizedError' /document/{path}: get: tags: - document summary: Get a document parameters: - $ref: '#/components/parameters/document_path' - $ref: '#/components/parameters/graph_type' - name: skip in: query description: Skip a certain amount of documents required: false schema: type: integer default: 0 - name: count in: query description: Number of entries to show required: false schema: type: integer example: 3 - name: minimized in: query description: Minify the output required: false schema: type: boolean default: true - name: as_list in: query description: Return the JSONs as list instead of concatenated json required: false schema: type: boolean default: false - name: unfold in: query description: Unfold the documents (join other referenced documents) schema: type: boolean default: true - name: id in: query required: false description: Specific document ID to look for schema: type: string example: Person_Robin_1991-02-01 - name: type in: query required: false description: Get documents of only a specific type schema: type: string example: Person - name: compress_ids in: query required: false description: Whether to compress all ids using prefixes schema: type: boolean default: true responses: 200: description: List of documents content: application/json: schema: type: object description: Concatenated list of JSON documents example: {"@id":"Organization/admin", "@type":"Organization", "database": ["SystemDatabase/system", "UserDatabase/60c35164e937174bbf4dd814c78153d660edc55b3d799c534c1e2d872a3d2dd6" ], "name":"admin"} post: tags: - document summary: Insert a new document parameters: - $ref: '#/components/parameters/document_path' - $ref: '#/components/parameters/author' - $ref: '#/components/parameters/message' - $ref: '#/components/parameters/graph_type' - name: full_replace in: query required: false description: Fully replace a document schema: type: boolean default: false - name: raw_json in: query required: false description: Whether to interpret the posted document as arbitrary untyped JSON schema: type: boolean default: false responses: 200: description: Succesfully added documents content: application/json: schema: type: object description: Added documents delete: tags: - document summary: Delete one or multiple documents parameters: - $ref: '#/components/parameters/document_path' - $ref: '#/components/parameters/author' - $ref: '#/components/parameters/message' - $ref: '#/components/parameters/graph_type' - name: nuke in: query description: Totally nuke the document(s) schema: type: boolean default: false - name: id in: query description: ID of document(s) schema: type: string example: admin/SomeDocument responses: 200: description: Succesfully deleted document(s) # TODO: Need the proper JSON resposne! put: tags: - document summary: Replace a document parameters: - $ref: '#/components/parameters/document_path' - $ref: '#/components/parameters/author' - $ref: '#/components/parameters/message' - $ref: '#/components/parameters/graph_type' - name: create in: query description: Create a document if it does not exist required: false schema: type: boolean default: false - name: raw_json in: query description: Treat incoming document as raw json (not type checked) required: false schema: type: boolean default: false responses: 200: description: Succesfully replaced documents /schema: get: tags: - frame summary: Get the full class frame for a class or all classes for a schema parameters: - $ref: '#/components/parameters/document_path' - name: compress_ids in: query description: Compress the URLs returned using prefixes required: false schema: type: boolean default: true - name: expand_abstract in: query description: Whether to expand abstract classes into lists of concrete classes in frame options required: false schema: type: boolean default: true responses: 200: description: Class Frame, or object of all class frames has been successfully returned content: application/json: schema: type: object examples: OneClass: value: { "@documentation": { "@comment":"A normal user database.","@properties": { "comment":"A comment associated with the database.", "creation_date":"The time of creation of the database.", "label":"The label name of the database.", "state":"The system transaction state of the database."} }, "@key": {"@type":"Random"}, "@type":"Class", "comment":"xsd:string", "creation_date":"xsd:dateTime","label":"xsd:string","name":"xsd:string","state": {"@id":"DatabaseState","@type":"Enum","@values": ["creating", "deleting", "finalized" ]}} AllClasses: value: { "@context": { "@base":"terminusdb:///data/", "@schema":"terminusdb:///schema#", "@type":"Context" }, "Person": {"@type":"Class", "name":"xsd:string"}, "Room": {"@type":"Class", "room_number":"xsd:integer"} } /woql: post: tags: - WOQL requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WoqlQuery' responses: 200: description: Query result /woql/{path}: post: tags: - WOQL parameters: - name: path description: Database Path in: path required: true schema: type: string example: admin/foo requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/WoqlQuery' responses: 200: description: Query result /clone/{organization}/{database}: post: tags: - collaboration parameters: - $ref: '#/components/parameters/organization' - $ref: '#/components/parameters/database' requestBody: required: true content: application/json: schema: type: object required: - comment - label - remote_url properties: comment: type: string example: This is a comment on my cloned database description: The comment to use in the cloned database label: type: string example: This is how I label my cloned database description: The label to use for the cloned database remote_url: type: string example: 'http://cloud.terminusdb.com/TerminatorsX/TerminatorsX/nuclear' description: The URL of the database to clone public: type: boolean description: Whether to make the newly cloned database public responses: 200: description: Database cloned succesfully content: application/json: schema: type: object /fetch/{path}: post: tags: - collaboration summary: Fetch the remote repository for the given path (default is origin) parameters: - $ref: '#/components/parameters/branch_path' - name: AUTHORIZATION_REMOTE in: header required: true description: The authorization to use on the remote schema: type: string example: Basic S2FybEthdXRza3k6cGFzc3dvcmRfZGVzdGluYXRpb24= responses: 200: description: "Successful fetch" content: application/json: schema: type: object properties: "@type:": type: string enum: - "api:FetchRequest" "api:status": type: string enum: - "api:success" "api:head_has_changed": type: boolean "api:head": type: string example: 194822f8942286517e151817d38acca4c9ac7d01 /push/{path}: post: summary: Push the branch to the remote tags: - collaboration parameters: - $ref: '#/components/parameters/branch_path' requestBody: required: true content: application/json: schema: type: object required: - remote - remote_branch properties: remote: type: string example: origin description: The name of the remote to push to remote_branch: type: string example: main description: The name of the branch on the remote to push push_prefixes: type: boolean default: false description: Should the prefixes also be pushed to the remote? responses: 200: description: "Push Response" content: application/json: schema: type: object properties: "@type": type: string enum: - "api:PushResponse" "api:repo_head_updated": type: boolean "api:repo_head": type: string example: 194822f8942286517e151817d38acca4c9ac7d01 "api:status": type: string enum: - "api:success" 400: description: "Push Response" content: application/json: schema: type: object properties: "@type": type: string enum: - "api:PushErrorResponse" "api:error": type: object "api:message": type: string example: "Unknown remote repository: porridgen" "api:status": type: string enum: - "api:failure" /pull/{path}: post: summary: Pull to a branch from a remote tags: - collaboration parameters: - $ref: '#/components/parameters/branch_path' requestBody: required: true content: application/json: schema: type: object required: - remote - remote_branch properties: remote: type: string example: origin description: The name of the remote to push to remote_branch: type: string example: main description: The name of the branch on the remote to push responses: 200: description: "Pull Response" content: application/json: schema: type: object properties: "@type": type: string enum: - "api:PullResponse" "api:status": type: string enum: - "api:success" /branch/{path}: post: tags: - branches parameters: - $ref: '#/components/parameters/branch_path' requestBody: required: true content: application/json: schema: type: object responses: 200: description: "Branch succesfully added" content: application/json: schema: type: object properties: "@type:": type: string enum: - "api:BranchResponse" "api:status": type: string enum: - "api:success" delete: tags: - branches parameters: - $ref: '#/components/parameters/branch_path' responses: 200: description: "Branch succesfully deleted" content: application/json: schema: type: object properties: "@type:": type: string enum: - "api:BranchResponse" "api:status": type: string enum: - "api:success" /squash/{path}: parameters: - $ref: '#/components/parameters/branch_path' get: tags: - branches responses: 200: description: "Succesfully squashed the branch" content: application/json: schema: type: object properties: "@type": type: string enum: - "api:SquashResponse" "api:commit": type: string example: admin/test/local/commit/apgatilsa03g4lsa9ra5698wom5wcv7 "api:old_commit": type: string example: admin/test/local/commit/5jndjh9lexe62q9u1q2vofyjemfnmyt "api:status": type: string enum: - api:success /reset/{path}: parameters: - $ref: '#/components/parameters/branch_path' post: tags: - branches requestBody: required: true content: application/json: schema: type: object properties: commit_descriptor: type: string example: admin/test/local/commit/5jndjh9lexe62q9u1q2vofyjemfnmyt responses: 200: description: "Succesfully reset branch HEAD to commit_descriptor" content: application/json: schema: type: object properties: "@type": type: string enum: - api:ResetResponse "api:status": type: string enum: - api:success /optimize/{path}: post: tags: - database parameters: - name: path description: Database Path in: path required: true schema: type: string example: _system responses: 200: description: Succesfully optimized resource content: application/json: schema: type: object properties: "@type": type: string enum: - api:OptimizeResponse "api:status": type: string enum: - api:success /prefixes/{path}: get: tags: - prefixes parameters: - name: path description: Database Path in: path required: true schema: type: string example: _system responses: 200: description: "Succesfully fetched prefixes of graph" content: application/json: schema: type: object /diff: post: tags: - change management requestBody: required: true content: application/json: schema: type: object properties: "before": type: object example: { "@id" : "Person/Jane", "@type" : "Person", "name" : "Jane"} "after": type: object example: { "@id" : "Person/Jane", "@type" : "Person", "name" : "Jannet"} "keep": type: object example: { "@id" : true, "_id" : true } responses: 200: description: "Successful Diff" content: application/json: schema: type: object example: { "name" : { "@op" : "ValueSwap", "@before" : "Jane", "@after": "Janine" }} 404: description: "Failed to find diff" /patch: post: tags: - change management requestBody: required: true content: application/json: schema: type: object properties: "before": type: object example: { "@id" : "Person/Jane", "@type" : "Person", "name" : "Jane"} "patch": type: object example: { "name" : { "@op" : "ValueSwap", "@before" : "Jane", "@after": "Janine" }} responses: 200: description: "Successful Patch" content: application/json: schema: type: object example: { "@id" : "Person/Jane", "@type" : "Person", "name" : "Jannet"} 404: description: "Failed to apply patch: returning conflict patch" content: application/json: schema: type: object example: { "name" : { "@op" : "ValueSwap", "@before" : "Doug", "@after": "Jane" }} components: parameters: graph_type: name: graph_type in: query description: Type of the graph required: false schema: type: string default: instance enum: - instance - schema author: name: author in: query description: Author of commit required: true schema: type: string example: Jan message: name: message in: query description: Commit message required: true schema: type: string example: Fixed bad name for document branch_path: name: path in: path description: Path for branch required: true schema: type: string example: admin/test/local/branch/foo document_path: name: path in: path description: Path for document required: true schema: type: string example: admin/foo organization: name: organization in: path description: Organization for the database required: true schema: type: string example: admin database: name: database in: path description: Database name required: true schema: type: string example: MyNewDatabase schemas: WoqlQuery: type: object properties: "query": type: object # TODO: Nice example of a WOQL Query description: WOQL Query "commit_info": $ref: "#/components/schemas/CommitInfo" "all_witnesses": type: boolean description: Check for all errors default: false CommitInfo: type: object properties: "author": type: string example: ExampleUser "message": type: string example: Created something in the data product Database: type: object properties: '@id': type: string example: UserDatabase/MyUserDatabase3315d1a3bb196e322e40bc53ac '@type': type: string example: UserDatabase comment: type: string example: A comment for my database creation_date: type: string example: 2021-12-13T14:27:46.202Z label: type: string example: MyDatabaseLabel name: type: string example: My Database Name state: type: string example: finalized responses: UnauthorizedError: description: Authentication information is missing or invalid content: application/json: schema: type: object properties: '@type': type: string example: api:ErrorResponse api:error: type: string api:message: type: string example: Incorrect authentication information api:status: type: string example: api:failure securitySchemes: basicAuth: type: http scheme: basic