Skip to main content

Tigris API Reference (0.0.1)

Download OpenAPI specification:Download

License: Apache License

Overview

This section is organized around HTTP APIs. The APIs accepts JSON requests and returns JSON-encoded responses.The APIs conforms to standard HTTP status codes.

Errors

Tigris uses conventional HTTP response codes to indicate the success or failure of an API request.The response will contain an error code or other information that reveals the reason of the error. The error response is in JSON format and is structured like this:

 {
   "error": {
     "code": "ALREADY_EXISTS",
     "message": "row already exists"
   }
 }

Status 2xx

HTTP Code Reason
200 - OK Everything worked as expected.

Status 4xx

Status codes in the 400-499 range indicate errors that have been caused by the requesting application (e.g., a malformed request body has been sent). Retrying such requests with the same request body is pointless and will result in the same status code again. Some 4xx errors can be handled programmatically. Change the request accordingly before retrying. Below you can find the most frequent 4XX errors and how to fix them.

HTTP Code Tigris Code Reason
400 - Bad Request INVALID_ARGUMENT The request was unacceptable, often due to missing a required parameter.
Examples:
  • Missing documents for write request
  • Collection or Database name is not following the allowed characters
  • 401 - Unauthorized UNAUTHENTICATED No valid API key provided. Check that your api_key and api_secret are correct.
    403 - Forbidden PERMISSION_DENIED The API key doesn't have permissions to perform the request.
    404 - Not Found NOT_FOUND The requested resource doesn't exist.
    Examples:
  • Database or Collection doesn't exists
  • Access Token missing in the request header
  • 409 - Conflict ALREADY_EXISTS TThe request conflicts with another request (perhaps due to using the same idempotent key).
    Examples:
  • Trying to insert document again for the primary key that already exists
  • Creating a database that already exists
  • 429 - Too Many Requests RESOURCE_EXHAUSTED Too many requests hit the API too quickly. We recommend an exponential backoff of your requests.

    Status 5xx

    The 5xx range indicate an error with Tigris servers (these are rare).

    HTTP Code Tigris Code Reason
    500 - Internal Server Error UNKNOWN Something went wrong on Tigris server side.
    501 - Not Implemented UNIMPLEMENTED Not supported by the Tigris server and cannot be handled.
    502 - Bad Gateway BAD_GATEWAY The API key doesn't have permissions to perform the request.
    503 - Service Unavailable UNAVAILABLE The server is not ready to handle the request. Common causes are a server that is down for maintenance or that is overloaded.
    504 - Gateway Timeout DEADLINE_EXCEEDED Tigris server is unable to process the request timely. Common causes are that request is expensive, or server is overloaded.

    Idempotent Requests

    Tigris provides idempotency guarantees when an API call is disrupted and either no response is returned or an HTTP Status code 429,500,501,502,503 is returned. These errors ensure that the request is not committed and retrying the same request will have the same effect.

    Limitations

  • Do not rely on case to distinguish between databases or collections names.
  • Database Name and Collection Name cannot be empty and can only have the characters matches the regex: ^[a-zA-Z]+[a-zA-Z0-9_]+$.
  • Duplicate field names are not allowed.
  • The maximum allowed document size is 100KB.
  • The maximum allowed transaction size is 10MB.
  • Application Keys

    The application keys section provide APIs that can be used to manage application keys for your project. A single project can have one or more application keys.

    List all the app keys

    Lists all app keys visible to requesting actor.

    Authorizations:
    BearerAuth
    path Parameters
    project
    required
    string

    Project name filter

    Responses

    Response samples

    Content type
    application/json
    {
    • "app_keys": [
      ]
    }

    Creates the app key

    Create an app key.

    Authorizations:
    BearerAuth
    path Parameters
    project
    required
    string

    Project name

    Request Body schema: application/json
    name
    string

    A human readable app name

    description
    string

    A human readable app description

    Responses

    Request samples

    Content type
    application/json
    {
    • "name": "string",
    • "description": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "created_app_key": {
      }
    }

    Deletes the app key

    Delete an app key.

    Authorizations:
    BearerAuth
    path Parameters
    project
    required
    string

    project name

    Request Body schema: application/json
    id
    string

    app_key id

    Responses

    Request samples

    Content type
    application/json
    {
    • "id": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "deleted": true
    }

    Rotates the app key secret

    Endpoint is used to rotate the secret for the app key.

    Authorizations:
    BearerAuth
    path Parameters
    project
    required
    string

    project name

    Request Body schema: application/json
    id
    string

    app key id

    project
    string

    project name

    Responses

    Request samples

    Content type
    application/json
    {
    • "id": "string",
    • "project": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "app_key": {
      }
    }

    Updates the description of the app key

    Update the description of an app key.

    Authorizations:
    BearerAuth
    path Parameters
    project
    required
    string

    project name - this is not allowed to update

    Request Body schema: application/json
    id
    string

    app key id - this is not allowed to update

    name
    string

    A new human readable app name

    description
    string

    A new human readable app description

    Responses

    Request samples

    Content type
    application/json
    {
    • "id": "string",
    • "name": "string",
    • "description": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "updated_app_key": {
      }
    }

    Authentication

    The auth section of API provides OAuth 2.0 APIs. Tigris supports pluggable OAuth provider. Pass the token in the headers for authentication, as an example -H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6I"(replace it with your token). All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

    Access Token

    Endpoint for receiving access token from Tigris Server. The endpoint requires Grant Type(grant_type) which has two possible values "REFRESH_TOKEN" or "CLIENT_CREDENTIALS" based on which either Refresh token(refresh_token) needs to be set or client credentials(client_id, client_secret).

    Authorizations:
    BearerAuth
    Request Body schema: x-www-form-urlencoded
    grant_type
    string <enum>
    Enum: "REFRESH_TOKEN" "CLIENT_CREDENTIALS"
    refresh_token
    string

    Refresh token is required when grant type is set as REFRESH_TOKEN.

    client_id
    string

    Client Id is required when grant type is set as CLIENT_CREDENTIALS.

    client_secret
    string

    Your Tigris API Key is required when grant type is set as CLIENT_CREDENTIALS.

    Responses

    Response samples

    Content type
    application/json
    {
    • "access_token": "string",
    • "refresh_token": "string",
    • "expires_in": 0
    }

    Cache

    The cache section provide APIs that can be used to perform cache operations.

    Lists all the caches for the given project

    Authorizations:
    BearerAuth
    path Parameters
    project
    required
    string

    Tigris project name

    Responses

    Response samples

    Content type
    application/json
    {
    • "caches": [
      ]
    }

    Creates the cache

    Authorizations:
    BearerAuth
    path Parameters
    project
    required
    string

    Tigris project name

    name
    required
    string

    cache name

    Request Body schema: application/json
    object (CreateCacheOptions)
    ttl_ms
    integer <uint64>

    Responses

    Request samples

    Content type
    application/json
    {
    • "options": {
      }
    }

    Response samples

    Content type
    application/json
    {
    • "message": "string",
    • "status": "string"
    }

    Deletes the cache

    Authorizations:
    BearerAuth
    path Parameters
    project
    required
    string

    Tigris project name

    name
    required
    string

    cache name

    Request Body schema: application/json
    object (DeleteCacheRequest)

    Responses

    Request samples

    Content type
    application/json
    { }

    Response samples

    Content type
    application/json
    {
    • "message": "string",
    • "status": "string"
    }

    Lists all the key for this cache

    Authorizations:
    BearerAuth
    path Parameters
    project
    required
    string

    Tigris project name

    name
    required
    string

    cache name

    query Parameters
    cursor
    integer <uint64>

    optional - cursor - skip this argument if no cursor is associated

    count
    integer <int64>

    optional - count of keys to return a stream response line.

    pattern
    string

    optional key pattern

    Responses

    Response samples

    Content type
    application/json
    {
    • "keys": [
      ],
    • "cursor": 0
    }

    Deletes an entry from cache

    Authorizations:
    BearerAuth
    path Parameters
    project
    required
    string

    Tigris project name

    name
    required
    string

    cache name

    key
    required
    string

    cache key

    Request Body schema: application/json
    object (DelRequest)

    Responses

    Request samples

    Content type
    application/json
    { }

    Response samples

    Content type
    application/json
    {
    • "message": "string",
    • "status": "string"
    }

    Reads an entry from cache

    Authorizations:
    BearerAuth
    path Parameters
    project
    required
    string

    Tigris project name

    name
    required
    string

    cache name

    key
    required
    string

    cache key

    Responses

    Response samples

    Content type
    application/json
    {
    • "value": "string",
    • "expires_in_ms": 0
    }

    Sets an entry in the cache and returns the previous value if exists

    Authorizations:
    BearerAuth
    path Parameters
    project
    required
    string

    Tigris project name

    name
    required
    string

    cache name

    key
    required
    string

    cache key

    Request Body schema: application/json
    value
    string <byte>

    free form byte[] value

    Responses

    Request samples

    Content type
    application/json
    {
    • "value": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "message": "string",
    • "status": "string",
    • "old_value": "string"
    }

    Sets an entry in the cache

    Authorizations:
    BearerAuth
    path Parameters
    project
    required
    string

    Tigris project name

    name
    required
    string

    cache name

    key
    required
    string

    cache key

    Request Body schema: application/json
    value
    string <byte>

    free form byte[] value

    ex
    integer <uint64>

    optional - ttl specific to this key in second

    px
    integer <uint64>

    optional - ttl specific to this key in millisecond

    nx
    boolean

    set only if the key doesn't exist

    xx
    boolean

    set only if the key exist

    Responses

    Request samples

    Content type
    application/json
    {
    • "value": "string",
    • "ex": 0,
    • "px": 0,
    • "nx": true,
    • "xx": true
    }

    Response samples

    Content type
    application/json
    {
    • "message": "string",
    • "status": "string"
    }

    Collections

    The Collections section provide APIs that can be used to manage collections. A collection can have one or more documents.

    Create or update a collection

    Creates a new collection or atomically upgrades the collection to the new schema provided in the request. Schema changes are applied atomically and immediately without any downtime. Tigris Offers two types of collections:

  • DOCUMENTS: Offers rich CRUD APIs.
  • MESSAGES: Offers event streaming APIs.

  • Authorizations:
    BearerAuth
    path Parameters
    project
    required
    string

    Project name whose db is under target to create or update collection.

    collection
    required
    string

    Collection name to create.

    Request Body schema: application/json
    schema
    object

    The schema specifications are same as JSON schema specification defined here.

    Schema example: { "title": "user", "description": "Collection of documents with details of users", "properties": { "id": { "description": "A unique identifier for the user", "type": "integer" }, "name": { "description": "Name of the user", "type": "string", "maxLength": 128 }, "balance": { "description": "User account balance", "type": "number" } }, "primary_key": ["id"] }

    only_create
    boolean

    If set to true then the update schema request to the collection will fail by returning a conflict with HTTP Status code 409. The default is false.

    options
    object (CollectionOptions)

    Collection requests modifying options.

    branch
    string

    Optionally specify a database branch name to perform operation on

    Responses

    Request samples

    Content type
    application/json
    {
    • "schema": { },
    • "only_create": true,
    • "options": { },
    • "branch": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "message": "string",
    • "status": "string"
    }

    Describe Collection

    Returns the information related to the collection. This can be used to retrieve the schema or size of the collection.

    Authorizations:
    BearerAuth
    path Parameters
    project
    required
    string

    Project name whose db is under target to get description of its collection.

    collection
    required
    string

    Name of the collection.

    Request Body schema: application/json
    project
    string

    Project name whose db is under target to get description of its collection.

    collection
    string

    Name of the collection.

    schema_format
    string

    Return schema in the requested format. Format can be JSON, Go, TypeScript, Java. Default is JSON.

    options
    object (CollectionOptions)

    Collection requests modifying options.

    branch
    string

    Optionally specify a database branch name to perform operation on

    Responses

    Request samples

    Content type
    application/json
    {
    • "project": "string",
    • "collection": "string",
    • "schema_format": "string",
    • "options": { },
    • "branch": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "collection": "string",
    • "metadata": { },
    • "schema": { },
    • "size": 0
    }

    Delete Documents

    Delete a range of documents in the collection using the condition provided in the filter.

    Authorizations:
    BearerAuth
    path Parameters
    project
    required
    string

    Project name whose db is under target to delete documents.

    collection
    required
    string

    Collection name where to insert documents.

    Request Body schema: application/json
    filter
    object

    Delete documents which matching specified filter. A filter can simply be key, value where key is the field name and value would be the value for this field. Or a filter can be logical where two or more fields can be logically joined using $or and $and. A few examples of filter:

  • To delete a user document where the id has a value 1: {"id": 1 }
  • To delete all the user documents where the key "id" has a value 1 or 2 or 3: {"$or": [{"id": 1}, {"id": 2}, {"id": 3}]}

  • object (DeleteRequestOptions)

    Additional options for deleted requests.

    branch
    string

    Optionally specify a database branch name to perform operation on

    Responses

    Request samples

    Content type
    application/json
    {
    • "filter": { },
    • "options": {
      },
    • "branch": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "metadata": {
      },
    • "status": "string"
    }

    Import Documents

    Imports documents into the collection.

    It automatically:

    • Detects the schema of the documents in the batch
    • Evolves the schema as soon as it's backward compatible
    • Creates collection with inferred schema (if requested)
    Authorizations:
    BearerAuth
    path Parameters
    project
    required
    string

    Project name whose db is under target to import documents.

    collection
    required
    string

    Collection name where to import documents.

    Request Body schema: application/json
    documents
    Array of objects

    Array of documents to import. Each document is a JSON object.

    object (ImportRequestOptions)

    additional options for import requests.

    branch
    string

    Optionally specify a database branch name to perform operation on

    create_collection
    boolean

    Allow to create collection if it doesn't exists

    primary_key
    Array of strings

    List of fields which constitutes primary key of the collection If not specified and field with name 'id' is present, it's used as a primary key, further if inferred type is UUID, then it's set as autogenerated.

    autogenerated
    Array of strings

    The list of autogenerated fields of the collection

    Responses

    Request samples

    Content type
    application/json
    {
    • "documents": [
      ],
    • "options": {
      },
    • "branch": "string",
    • "create_collection": true,
    • "primary_key": [
      ],
    • "autogenerated": [
      ]
    }

    Response samples

    Content type
    application/json
    {
    • "metadata": {
      },
    • "status": "string",
    • "keys": [
      ]
    }

    Insert Documents

    Inserts new documents in the collection and returns an AlreadyExists error if any of the documents in the request already exists. Insert provides idempotency by returning an error if the document already exists. To replace documents, use REPLACE API instead of INSERT.

    Authorizations:
    BearerAuth
    path Parameters
    project
    required
    string

    Project name whose db is under target to insert documents.

    collection
    required
    string

    Collection name where to insert documents.

    Request Body schema: application/json
    documents
    Array of objects

    Array of documents to insert. Each document is a JSON object.

    object (InsertRequestOptions)

    additional options for insert requests.

    branch
    string

    Optionally specify a database branch name to perform operation on

    Responses

    Request samples

    Content type
    application/json
    {
    • "documents": [
      ],
    • "options": {
      },
    • "branch": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "metadata": {
      },
    • "status": "string",
    • "keys": [
      ]
    }

    Read Documents

    Reads a range of documents from the collection, or messages from a collection in case of event streaming. Tigris does not require you to index any fields and automatically index all the fields which means you can filter by any field in the document. An empty filter will trigger reading all the documents inside this collection. The API supports pagination that can be used by passing Limit/Skip parameters. The skip parameter skips the number of documents from the start and the limit parameter is used to specify the number of documents to read. You can find more detailed documentation of the Read API here.

    Authorizations:
    BearerAuth
    path Parameters
    project
    required
    string

    Project name whose db is under target to read documents from.

    collection
    required
    string

    Collection name to read documents from.

    Request Body schema: application/json
    filter
    object

    Returns documents matching this filter. A filter can simply be a key, value pair where a key is the field name and the value would be the value for this field. Tigris also allows complex filtering by passing logical expressions. Logical filters are applied on two or more fields using $or and $and. A few examples of filters:

  • To read a user document where the id has a value 1: {"id": 1 }
  • To read all the user documents where the key "id" has a value 1 or 2 or 3: {"$or": [{"id": 1}, {"id": 2}, {"id": 3}]} Filter allows setting collation on an individual field level. To set collation for all the fields see options. The detailed documentation of the filter is here.

  • fields
    object

    To read specific fields from a document. Default is all.

    object (ReadRequestOptions)

    Options that can be used to modify the results, for example "limit" to control the number of documents returned by the server.

    sort
    string <byte>

    Array of fields and corresponding sort orders to order the results. Ex: 1 [{ "salary": "$desc" }], Ex: 2 [{ "salary": "$asc"}]

    branch
    string

    Optionally specify a database branch name to perform operation on

    Responses

    Request samples

    Content type
    application/json
    {
    • "filter": { },
    • "fields": { },
    • "options": {
      },
    • "sort": "string",
    • "branch": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "result": {
      },
    • "error": {
      }
    }

    Insert or Replace Documents

    Inserts the documents or replaces the existing documents in the collections.

    Authorizations:
    BearerAuth
    path Parameters
    project
    required
    string

    Project name whose db is under target to replace documents.

    collection
    required
    string

    Collection name where to replace documents.

    Request Body schema: application/json
    documents
    Array of objects

    Array of documents to be replaced. Each document is a JSON object.

    object (ReplaceRequestOptions)

    Additional options for replace requests.

    branch
    string

    Optionally specify a database branch name to perform operation on

    Responses

    Request samples

    Content type
    application/json
    {
    • "documents": [
      ],
    • "options": {
      },
    • "branch": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "metadata": {
      },
    • "status": "string",
    • "keys": [
      ]
    }

    Update Documents.

    Update a range of documents in the collection using the condition provided in the filter.

    Authorizations:
    BearerAuth
    path Parameters
    project
    required
    string

    Project name whose db is under target to update documents

    collection
    required
    string

    Collection name where to update documents

    Request Body schema: application/json
    fields
    object

    Fields contains set of fields with the values which need to be updated. Should be proper JSON object.

    filter
    object

    Update documents which matching specified filter. A filter can simply be key, value where key is the field name and value would be the value for this field. Or a filter can be logical where two or more fields can be logically joined using $or and $and. A few examples of filter:

  • To update a user document where the id has a value 1: {"id": 1 }
  • To update all the user documents where the key "id" has a value 1 or 2 or 3: {"$or": [{"id": 1}, {"id": 2}, {"id": 3}]}

  • object (UpdateRequestOptions)

    Additional options for update requests.

    branch
    string

    Optionally specify a database branch name to perform operation on

    Responses

    Request samples

    Content type
    application/json
    {
    • "fields": { },
    • "filter": { },
    • "options": {
      },
    • "branch": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "metadata": {
      },
    • "modified_count": 0,
    • "status": "string"
    }

    Drop Collection

    Drops the collection inside this project. This API deletes all of the documents inside this collection and any metadata associated with it.

    Authorizations:
    BearerAuth
    path Parameters
    project
    required
    string

    Project name whose db is under target to delete collection.

    collection
    required
    string

    Collection name to delete.

    Request Body schema: application/json
    options
    object (CollectionOptions)

    Collection requests modifying options.

    branch
    string

    Optionally specify a project branch name to perform operation on

    Responses

    Request samples

    Content type
    application/json
    {
    • "options": { },
    • "branch": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "message": "string",
    • "status": "string"
    }

    Database

    The Database section provide APIs that can be used to interact with the database. A single Database can have one or more collections. A database is created automatically for you when you create a project.

    Create a database branch

    Creates a new database branch, if not already existing.

    Authorizations:
    BearerAuth
    path Parameters
    project
    required
    string

    Create a database branch in this project

    branch
    required
    string

    Name of the database branch to be created.

    Note: main is a reserved branch name for primary database and is automatically created with CreateProject

    Request Body schema: application/json
    object (CreateBranchRequest)

    Responses

    Request samples

    Content type
    application/json
    { }

    Response samples

    Content type
    application/json
    {
    • "message": "string",
    • "status": "string"
    }

    Delete a database branch

    Deletes a database branch, if exists. Throws 400 Bad Request if "main" branch is being deleted

    Authorizations:
    BearerAuth
    path Parameters
    project
    required
    string

    Delete a database branch in this project

    branch
    required
    string

    Name of the database branch to delete.

    Note: main branch cannot be deleted, use DeleteProject instead

    Request Body schema: application/json
    object (DeleteBranchRequest)

    Responses

    Request samples

    Content type
    application/json
    { }

    Response samples

    Content type
    application/json
    {
    • "message": "string",
    • "status": "string"
    }

    List Collections

    List all the collections present in the project passed in the request.

    Authorizations:
    BearerAuth
    path Parameters
    project
    required
    string

    Project name whose db is under target to list collections.

    query Parameters
    branch
    string

    Optionally specify a database branch name to perform operation on

    Responses

    Response samples

    Content type
    application/json
    {
    • "collections": [
      ]
    }

    Describe database

    This API returns information related to the project along with all the collections inside the project. This can be used to retrieve the size of the project or to retrieve schemas, branches and the size of all the collections present in this project.

    Authorizations:
    BearerAuth
    path Parameters
    project
    required
    string

    Project name whose db is under target to get description.

    Request Body schema: application/json
    project
    string

    Project name whose db is under target to get description.

    schema_format
    string

    Return schema in the requested format. Format can be JSON, Go, TypeScript, Java. Default is JSON.

    branch
    string

    Optionally specify a database branch name to perform operation on

    Responses

    Request samples

    Content type
    application/json
    {
    • "project": "string",
    • "schema_format": "string",
    • "branch": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "metadata": { },
    • "collections": [
      ],
    • "size": 0,
    • "branches": [
      ]
    }

    Begin a transaction

    Starts a new transaction and returns a transactional object. All reads/writes performed within a transaction will run with serializable isolation. Tigris offers global transactions, with ACID properties and strict serializability.

    Authorizations:
    BearerAuth
    path Parameters
    project
    required
    string

    Project name whose DB this transaction belongs to.

    Request Body schema: application/json
    options
    object (TransactionOptions)

    Options that can be used to modify the transaction semantics.

    branch
    string

    Optionally specify a project branch name to perform operation on

    Responses

    Request samples

    Content type
    application/json
    {
    • "options": { },
    • "branch": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "tx_ctx": {
      }
    }

    Commit a Transaction

    Atomically commit all the changes performed in the context of the transaction. Commit provides all or nothing semantics by ensuring no partial updates are in the project due to a transaction failure.

    Authorizations:
    BearerAuth
    path Parameters
    project
    required
    string

    Project name whose DB this transaction belongs to.

    Request Body schema: application/json
    branch
    string

    Optionally specify a database branch name to perform operation on

    Responses

    Request samples

    Content type
    application/json
    {
    • "branch": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "status": "string"
    }

    Rollback a transaction

    Rollback transaction discards all the changes performed in the transaction

    Authorizations:
    BearerAuth
    path Parameters
    project
    required
    string

    Project name whose DB this transaction belongs to.

    Request Body schema: application/json
    branch
    string

    Optionally specify a database branch name to perform operation on

    Responses

    Request samples

    Content type
    application/json
    {
    • "branch": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "status": "string"
    }

    Management

    The Management section provide APIs that can be used to manage users, and app_keys.

    Reads the Namespace Metadata

    GetNamespaceMetadata inserts the user metadata object

    Authorizations:
    BearerAuth
    path Parameters
    metadataKey
    required
    string
    Request Body schema: application/json
    metadataKey
    string
    value
    object

    Responses

    Request samples

    Content type
    application/json
    {
    • "metadataKey": "string",
    • "value": { }
    }

    Response samples

    Content type
    application/json
    {
    • "metadataKey": "string",
    • "namespaceId": 0,
    • "value": { }
    }

    Inserts Namespace Metadata

    InsertNamespaceMetadata inserts the namespace metadata object

    Authorizations:
    BearerAuth
    path Parameters
    metadataKey
    required
    string
    Request Body schema: application/json
    metadataKey
    string
    value
    object

    Responses

    Request samples

    Content type
    application/json
    {
    • "metadataKey": "string",
    • "value": { }
    }

    Response samples

    Content type
    application/json
    {
    • "metadataKey": "string",
    • "namespaceId": 0,
    • "value": { }
    }

    Updates Namespace Metadata

    UpdateNamespaceMetadata updates the user metadata object

    Authorizations:
    BearerAuth
    path Parameters
    metadataKey
    required
    string
    Request Body schema: application/json
    metadataKey
    string
    value
    object

    Responses

    Request samples

    Content type
    application/json
    {
    • "metadataKey": "string",
    • "value": { }
    }

    Response samples

    Content type
    application/json
    {
    • "metadataKey": "string",
    • "namespaceId": 0,
    • "value": { }
    }

    Creates a Namespace

    Creates a new namespace, if it does not exist

    Authorizations:
    BearerAuth
    Request Body schema: application/json
    code
    integer <uint32>

    Optional: unique id

    id
    string

    Optional: unique string id

    name
    string

    Required: The display name for namespace.

    Responses

    Request samples

    Content type
    application/json
    {
    • "code": 0,
    • "id": "string",
    • "name": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "message": "string",
    • "status": "string",
    • "namespace": {
      }
    }

    Describe the details of all namespaces

    Get details for all namespaces

    Authorizations:
    BearerAuth

    Responses

    Response samples

    Content type
    application/json
    {
    • "data": {
      }
    }

    Lists all Namespaces

    List all namespace

    Authorizations:
    BearerAuth

    Responses

    Response samples

    Content type
    application/json
    {
    • "namespaces": [
      ]
    }

    Reads the User Metadata

    GetUserMetadata inserts the user metadata object

    Authorizations:
    BearerAuth
    path Parameters
    metadataKey
    required
    string
    Request Body schema: application/json
    metadataKey
    string
    value
    object

    Responses

    Request samples

    Content type
    application/json
    {
    • "metadataKey": "string",
    • "value": { }
    }

    Response samples

    Content type
    application/json
    {
    • "metadataKey": "string",
    • "userId": "string",
    • "namespaceId": 0,
    • "value": "string"
    }

    Inserts User Metadata

    insertUserMetadata inserts the user metadata object

    Authorizations:
    BearerAuth
    path Parameters
    metadataKey
    required
    string
    Request Body schema: application/json
    metadataKey
    string
    value
    object

    Responses

    Request samples

    Content type
    application/json
    {
    • "metadataKey": "string",
    • "value": { }
    }

    Response samples

    Content type
    application/json
    {
    • "metadataKey": "string",
    • "userId": "string",
    • "namespaceId": 0,
    • "value": { }
    }

    Updates User Metadata

    updateUserMetadata updates the user metadata object

    Authorizations:
    BearerAuth
    path Parameters
    metadataKey
    required
    string
    Request Body schema: application/json
    metadataKey
    string
    value
    object

    Responses

    Request samples

    Content type
    application/json
    {
    • "metadataKey": "string",
    • "value": { }
    }

    Response samples

    Content type
    application/json
    {
    • "metadataKey": "string",
    • "userId": "string",
    • "namespaceId": 0,
    • "value": { }
    }

    Observability

    The Observability section has APIs that provides full visibility into the health, metrics, and monitoring of the Server.

    Health Check

    This endpoint can be used to check the liveness of the server.

    Responses

    Response samples

    Content type
    application/json
    {
    • "response": "string"
    }

    Information about the server

    Provides the information about the server. This information includes returning the server version, etc.

    Authorizations:
    BearerAuth

    Responses

    Response samples

    Content type
    application/json
    {
    • "server_version": "string"
    }

    Queries time series metrics

    Queries time series metrics

    Authorizations:
    BearerAuth
    Request Body schema: application/json
    db
    string
    collection
    string
    from
    integer <int64>
    to
    integer <int64>
    metric_name
    string
    tigris_operation
    string <enum>
    Enum: "ALL" "READ" "WRITE" "METADATA"
    space_aggregation
    string <enum>
    Enum: "AVG" "MIN" "MAX" "SUM"
    space_aggregated_by
    Array of strings
    function
    string <enum>
    Enum: "RATE" "COUNT" "NONE"
    quantile
    number <float>
    Array of objects (AdditionalFunction)

    Responses

    Request samples

    Content type
    application/json
    {
    • "db": "string",
    • "collection": "string",
    • "from": 0,
    • "to": 0,
    • "metric_name": "string",
    • "tigris_operation": "ALL",
    • "space_aggregation": "AVG",
    • "space_aggregated_by": [
      ],
    • "function": "RATE",
    • "quantile": 0,
    • "additionalFunctions": [
      ]
    }

    Response samples

    Content type
    application/json
    {
    • "from": 0,
    • "to": 0,
    • "query": "string",
    • "series": [
      ]
    }

    Queries current namespace quota limits

    Returns current namespace quota limits

    Authorizations:
    BearerAuth
    Request Body schema: application/json
    object (QuotaLimitsRequest)

    Request current namespace quota limits

    Responses

    Request samples

    Content type
    application/json
    { }

    Response samples

    Content type
    application/json
    {
    • "ReadUnits": 0,
    • "WriteUnits": 0,
    • "StorageSize": 0
    }

    Queries current namespace quota usage

    Returns current namespace quota limits

    Authorizations:
    BearerAuth
    Request Body schema: application/json
    object (QuotaUsageRequest)

    Request current namespace quota usage

    Responses

    Request samples

    Content type
    application/json
    { }

    Response samples

    Content type
    application/json
    {
    • "ReadUnits": 0,
    • "WriteUnits": 0,
    • "StorageSize": 0,
    • "ReadUnitsThrottled": 0,
    • "WriteUnitsThrottled": 0,
    • "StorageSizeThrottled": 0
    }

    Projects

    Every Tigris projects comes with a transactional document database built on FoundationDB, one of the most resilient and battle-tested open source distributed key-value store. A database is created automatically for you when you create a project.

    List Projects

    List returns all the projects.

    Authorizations:
    BearerAuth

    Responses

    Response samples

    Content type
    application/json
    {
    • "projects": [
      ]
    }

    Create Project

    Creates a new project. Returns an AlreadyExists error with a status code 409 if the project already exists.

    Authorizations:
    BearerAuth
    path Parameters
    project
    required
    string

    Create project with this name.

    Request Body schema: application/json
    object (CreateProjectRequest)

    Responses

    Request samples

    Content type
    application/json
    { }

    Response samples

    Content type
    application/json
    {
    • "message": "string",
    • "status": "string"
    }

    Delete Project and all resources under project

    Delete Project deletes all the collections in this project along with all of the documents, and associated metadata for these collections.

    Authorizations:
    BearerAuth
    path Parameters
    project
    required
    string

    Delete Project with this name.

    Note: Deletes all resources under this project. Use with caution.

    Request Body schema: application/json
    object (DeleteProjectRequest)

    Responses

    Request samples

    Content type
    application/json
    { }

    Response samples

    Content type
    application/json
    {
    • "message": "string",
    • "status": "string"
    }

    Realtime

    The realtime section provide APIs that can be used realtime operations.

    Get all channels for your application project

    Authorizations:
    BearerAuth
    path Parameters
    project
    required
    string

    Responses

    Response samples

    Content type
    application/json
    {
    • "channels": [
      ]
    }

    Get the details about a channel

    Authorizations:
    BearerAuth
    path Parameters
    project
    required
    string
    channel
    required
    string

    Responses

    Response samples

    Content type
    application/json
    {
    • "channel": "string"
    }

    Get all messages for a channel

    Authorizations:
    BearerAuth
    path Parameters
    project
    required
    string
    channel
    required
    string
    query Parameters
    session_id
    string
    socket_id
    string
    event
    string
    start
    string
    end
    string
    limit
    integer <int64>

    Responses

    Response samples

    Content type
    application/json
    {
    • "message": {
      }
    }

    push messages to a single channel

    Authorizations:
    BearerAuth
    path Parameters
    project
    required
    string
    channel
    required
    string
    Request Body schema: application/json
    project
    string
    channel
    string
    Array of objects (Message)

    Responses

    Request samples

    Content type
    application/json
    {
    • "project": "string",
    • "channel": "string",
    • "messages": [
      ]
    }

    Response samples

    Content type
    application/json
    {
    • "ids": [
      ]
    }

    Presence about the channel

    Authorizations:
    BearerAuth
    path Parameters
    project
    required
    string
    channel
    required
    string

    Responses

    Response samples

    Content type
    application/json
    {
    • "response": "string"
    }

    Get the subscriptions details about a channel

    Authorizations:
    BearerAuth
    path Parameters
    project
    required
    string
    channel
    required
    string
    query Parameters
    page_size
    integer <int32>
    page
    integer <int32>

    Responses

    Response samples

    Content type
    application/json
    {
    • "devices": [
      ]
    }

    Search

    List search indexes

    Authorizations:
    BearerAuth
    path Parameters
    project
    required
    string

    Tigris project name.

    Responses

    Response samples

    Content type
    application/json
    {
    • "indexes": [
      ]
    }

    Get a single or multiple documents

    Retrieves one or more documents by id. The response is an array of documents in the same order it is requests. A null is returned for the documents that are not found.

    Authorizations:
    BearerAuth
    path Parameters
    project
    required
    string

    Project name whose db is under target to insert documents.

    index
    required
    string

    index name where to create documents.

    query Parameters
    ids
    Array of strings

    document id.

    Responses

    Response samples

    Content type
    application/json
    {
    • "documents": [
      ]
    }

    Create or replace documents in an index

    Creates or replaces one or more documents. Each document is a JSON object. A document is replaced if it already exists. An "id" is generated automatically in case it is missing in the document. The document is created if "id" doesn't exists otherwise it is replaced. Returns an array of status indicating the status of each document.

    Authorizations:
    BearerAuth
    path Parameters
    project
    required
    string

    Project name whose db is under target to insert documents.

    index
    required
    string

    index name where to create documents.

    Request Body schema: application/json
    project
    string

    Project name whose db is under target to insert documents.

    index
    string

    index name where to create documents.

    documents
    Array of strings <byte>

    An array of documents to create. Each document is a JSON object. In case an id is missing then the server will automatically generate it for you and create the document and in case an id is provided in the document and the document already exists then that document will not index and in the response there will be an error corresponding to that document id other documents will succeed.

    Responses

    Request samples

    Content type
    application/json
    {
    • "project": "string",
    • "index": "string",
    • "documents": [
      ]
    }

    Response samples

    Content type
    application/json
    {
    • "status": [
      ]
    }

    Create multiple documents

    Create is used for indexing a single or multiple documents. The API expects an array of documents. Each document is a JSON object. An "id" is optional and the server can automatically generate it for you in case it is missing. In cases when an id is provided in the document and the document already exists then that document will not be indexed and in the response there will be an error corresponding to that document id other documents will succeed. Returns an array of status indicating the status of each document.

    Authorizations:
    BearerAuth
    path Parameters
    project
    required
    string

    Tigris project name.

    index
    required
    string

    index name where to create documents.

    Request Body schema: application/json
    project
    string

    Tigris project name.

    index
    string

    index name where to create documents.

    documents
    Array of strings <byte>

    An array of documents to be created or replaced. Each document is a JSON object.

    Responses

    Request samples

    Content type
    application/json
    {
    • "project": "string",
    • "index": "string",
    • "documents": [
      ]
    }

    Response samples

    Content type
    application/json
    {
    • "status": [
      ]
    }

    Delete documents by ids

    Delete one or more documents by id. Returns an array of status indicating the status of each document. Each status has an error field that is set to null in case document is deleted successfully otherwise it will non null with an error code and message.

    Authorizations:
    BearerAuth
    path Parameters
    project
    required
    string

    The project name.

    index
    required
    string

    The index name of the documents that needs deletion.

    Request Body schema: application/json
    project
    string

    The project name.

    index
    string

    The index name of the documents that needs deletion.

    ids
    Array of strings

    A list of ids

    Responses

    Request samples

    Content type
    application/json
    {
    • "project": "string",
    • "index": "string",
    • "ids": [
      ]
    }

    Response samples

    Content type
    application/json
    {
    • "status": [
      ]
    }

    Update documents in an index

    Updates one or more documents by "id". Each document is required to have the "id" field in it. Returns an array of status indicating the status of each document. Each status has an error field that is set to null in case document is updated successfully otherwise the error field is set with a code and message.

    Authorizations:
    BearerAuth
    path Parameters
    project
    required
    string

    Project name whose db is under target to insert documents.

    index
    required
    string

    Index name where to create documents.

    Request Body schema: application/json
    project
    string

    Project name whose db is under target to insert documents.

    index
    string

    Index name where to create documents.

    documents
    Array of strings <byte>

    An array of documents. Each document should have "id" present which will be used by Tigris for updating the document.

    Responses

    Request samples

    Content type
    application/json
    {
    • "project": "string",
    • "index": "string",
    • "documents": [
      ]
    }

    Response samples

    Content type
    application/json
    {
    • "status": [
      ]
    }

    Update documents in an index

    Updates one or more documents by "id". Each document is required to have the "id" field in it. Returns an array of status indicating the status of each document. Each status has an error field that is set to null in case document is updated successfully otherwise the error field is set with a code and message.

    Authorizations:
    BearerAuth
    path Parameters
    project
    required
    string

    Project name whose db is under target to insert documents.

    index
    required
    string

    Index name where to create documents.

    Request Body schema: application/json
    project
    string

    Project name whose db is under target to insert documents.

    index
    string

    Index name where to create documents.

    documents
    Array of strings <byte>

    An array of documents. Each document should have "id" present which will be used by Tigris for updating the document.

    Responses

    Request samples

    Content type
    application/json
    {
    • "project": "string",
    • "index": "string",
    • "documents": [
      ]
    }

    Response samples

    Content type
    application/json
    {
    • "status": [
      ]
    }

    Delete documents by query

    DeleteByQuery is used to delete documents that match the filter. A filter is required. To delete document by id, you can pass the filter as follows {"id": "test"}. Returns a count of number of documents deleted.

    Authorizations:
    BearerAuth
    path Parameters
    project
    required
    string

    The project name.

    index
    required
    string

    The index name of the documents that needs deletion.

    Request Body schema: application/json
    project
    string

    The project name.

    index
    string

    The index name of the documents that needs deletion.

    filter
    string <byte>

    A filter is required to delete matching documents. To delete document by id, you can pass the filter as follows {"id": "test"}

    Responses

    Request samples

    Content type
    application/json
    {
    • "project": "string",
    • "index": "string",
    • "filter": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "count": 0
    }

    Create a single document

    CreateById is used for indexing a single document. The API expects a single document. An "id" is optional and the server can automatically generate it for you in case it is missing. In cases an id is provided in the document and the document already exists then that document will not be indexed and an error is returned with HTTP status code 409.

    Authorizations:
    BearerAuth
    path Parameters
    project
    required
    string

    Tigris project name.

    index
    required
    string

    index name where to create document.

    id
    required
    string

    document id.

    Request Body schema: application/json
    project
    string

    Tigris project name.

    index
    string

    index name where to create document.

    id
    string

    document id.

    document
    string <byte>

    A JSON document that needs to be indexed.

    Responses

    Request samples

    Content type
    application/json
    {
    • "project": "string",
    • "index": "string",
    • "id": "string",
    • "document": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "id": "string"
    }

    Creates or updates search index

    Authorizations:
    BearerAuth
    path Parameters
    project
    required
    string

    Tigris project name.

    name
    required
    string

    search index name.

    Request Body schema: application/json
    project
    string

    Tigris project name.

    name
    string

    search index name.

    schema
    string <byte>

    schema of the index. The schema specifications are same as JSON schema specification defined here.

    Schema example: { "title": "ecommerce_index", "description": "an ecommerce store search index", "properties": { "name": { "description": "Name of the product", "type": "string", "maxLength": 128 }, "brand": { "description": "Brand of the product", "type": "string" }, "price": { "description": "Price of the product", "type": "number" } } }

    only_create
    boolean

    If set to true then a conflict with HTTP Status code 409 is returned if an index already exists. The default is false.

    Responses

    Request samples

    Content type
    application/json
    {
    • "project": "string",
    • "name": "string",
    • "schema": "string",
    • "only_create": true
    }

    Response samples

    Content type
    application/json
    {
    • "message": "string",
    • "status": "string"
    }

    Deletes search index

    Authorizations:
    BearerAuth
    path Parameters
    project
    required
    string

    Tigris project name.

    name
    required
    string

    index name.

    Request Body schema: application/json
    project
    string

    Tigris project name.

    name
    string

    index name.

    Responses

    Request samples

    Content type
    application/json
    {
    • "project": "string",
    • "name": "string"
    }

    Response samples

    Content type
    application/json
    {
    • "message": "string",
    • "status": "string"
    }