capito.ai is a product of the CFS GesmbH which specializes on the automated analysis and simplification (including translation) of texts.
These languages are actively being worked on and therefore may lack some features compared to the fully supported ones.
This page aims to provide information on how to access our API and describe the design & concepts used for the API. For more information on the endpoints themselves please use the provided OpenAPI-3.1 compatible YAML-File (please see below for details).
To simplify the access to our API, we also provide an OpenAPI-3.1 compatible YAML-File. This file can be found here.
We also provide two User-Interfaces to display the Open-API specification:
Our API can be accessed using either a dedicated API-Token or JSON-Web-Token (deprecated).
If the authentication fails, the API will respond with HTTP-Status
Code 401 with more information on the reason in the
body:
{
"property": "header::Authorization",
"message": "<<the actual error message>>"
}To gain access to our API, dedicated API-Tokens are the recommended way. These provide an easy way to access the API, since they do not expire (in contrast to the JSON-Web-Tokens).
Those API-Tokens can be managed (created & revoked)
using the App (found under
Settings > API).
A maximum of 5 API-Tokens can be used at one time by a single user.
API-Tokens are a random string with a length of 64
characters and match the regular expression
^[2-9A-HJ-NP-Za-km-z]{64}$.
To use the API-Token it must be sent to the API in each request in the HTTP-Headers:
Authorization: Token <<API-Token>>This method is deprecated and not recommended to access our API. It is still documented for the sake of completeness.
Our App uses JSON-Web-Tokens (Access Token) to authenticate. Those tokens are fetched from our Authentication-Provider Auth0 and are then sent to the API using the Bearer-Schema in the HTTP-Headers.
To use the API-Token it must be sent to the API in each request in the HTTP-Headers:
Authorization: Bearer <<JWT>>The JSON-Web-Token (JWT) can be copied from the requests in the browser (using the built-in Dev-Tools) for troubleshooting purposes or to set up dedicated API-Tokens if none has been generated before using the API directly instead of using the App.
The API can be mostly interpreted as a RESTlike-API that uses the HTTP-Method to determine the type of action to take, and the path to determine what resource to create/modify/delete.
The API is also designed around the concept of an Account.
An Account can be either
A User-Account can be understood as a “common” Account for which a user has to have credentials to be able to gain access. When creating a new Account in our App, a User-Account is created.
Important: This is the only type of Account that can gain access to the API using either API-Tokens or JSON-Web-Tokens!
A Team-Account is a special type of Account that allows for grouping of settings, payment etc. of other Accounts. This allows for a single Account to handle, for example, the subscription / quota that can be used by many Accounts.
A Team-Account can be created by any User-Account
(as long as the User-Account is verified; see
chapter Authorization for more information).
A Team-Account can be modified / deleted by any
User-Account that has the Team-Account specific role
admin (see chapter Authorization for more
information).
For now, only User-Accounts can be added to Team-Accounts.
Most endpoints of our API accept a parameter
{account-id}. This parameter allow the API to determine
which Account the action should be performed on/with.
To make using the API easier, a special value me is also
allowed. This value will be replaced internally for the
Account-ID that is derived from the
Authorization.
The Account-ID can be found in the decoded JSON-Web-Token
for that User-Account. It is not recommended
to use this Account-ID directly but instead just use the
special value me.
For Team-Accounts the Account-ID can be found when querying for the Team-Accounts for which the currently authorized user is a member of. For more information on the endpoints available, please see the chapter OpenAPI-Specification above.
The API uses roles to determine which actions an Account is allowed to take. Depending on the type of Account those roles differ.
In the description of each endpoint in the OpenAPI-File should be information about which roles are required for an Account to be assigned to in order to take that action or gain access to the resource.
This type of Account can have the following roles
This role is the default role when a new User-Account is created and is always present.
This role indicates if a User-Account has been verified, i.e. the verification flow for the Email has completed successfully.
This gains additional access to actions and resources, like being able to query for an analysis or translation.
For a User-Account to be considered verified, the email-address that the user uses for logging into the User-Account needs to be verified.
This is done using the following steps in the App:
Confirm email addressverifiedThis role may be assigned by our support team to a User-Account to grant additional permission to access certain resources and take specific actions.
This role is solely used for giving feedback on the analysis and simplification results and will not concern most users.
When a User-Account is assigned to a Team-Account, it is also assigned one or more roles. These roles are:
Depending on the role, the User-Account is able to take certain actions on behalf of the Team-Account.