Using the API

Once you've signed up for an account, you're ready to access the API. Signing up creates not just your user account, but also a team workspace where you can invite your colleagues. You access Noematic through your own user account, but any content or resources you create are visible to your entire team.

Authentication

Before you can trigger actions using the API, you'll need to retrieve your API token. API tokens are unique to individual users. If you delete a user from a team, their API token will no longer function.

Once you're logged in, you can find your API token by clicking the icon on the sidebar. You're now ready to make your first API call.

Making your first request

Noematic uses a JSON-based HTTP API. You can access the API through your HTTP client or library of choice.

• The request method and URL remain constant across all requests.
  • You must dispatch POST requests to https://api.noematic.ai.
• Two request headers must be specified.
  • The
    stringContent-Type
    header must always be set to application/json.
  • The
    stringAuthorization
    header must be set to the concatenation of the keyword Bearer and your API key, separated by a space.
• All other request data must be encoded in a JSON object and placed in the request body. The object may contain the following keys:
  • stringaction
    is required and indicates what you're trying to retrieve or trigger.
  • stringview
    indicates on behalf of whom you're trying to execute this action. Usually, you'll be acting on behalf of your own user account (with a view of user), or your team (with a view of team).
  • stringversion
    indicates the version of the API to use. Use the value found in the documentation at the time of reading. Not all actions may be supported in all versions. If no version is provided, the latest version will be used.
  • anydata
    is used for additional action-specific data. Some actions require no additional data; in such cases the field will be omitted in the documentation.

To see this in action, let's dispatch an API call that expects a character string in data, and returns that exact value back.

{
    "version": "1.0",
    "view": "user",
    "action": "echo",
    "data": "My first request!"
}

If all goes well, you should receive a response like the following, with a JSON-encoded response body. If the request is successful, the response object will only contain a

{
    "data": "My first request!"
}

Read on to find out what happens when a request is unsuccesful.

Handling errors

Requests can sometimes fail. Perhaps the request body was invalid, or maybe there has been a transient server error. In cases like these, the response object will contain an

To see this in action, let's run an API call for an echo action as before, but use a number in the request data.

{
    "version": "1.0",
    "view": "user",
    "action": "echo",
    "data": 42
}

This fails as this action expects a character string. The response object has a single errors key, without data.

{
    "errors": [
        {
            "code": "bad_type",
            "message": "Must be a string.",
            "params": [],
            "extra": null
        }
    ]
}

Response errors are always JSON arrays of objects with 4 keys.

• stringcode
  is a machine-readable identifier of the error.
• stringmessage
  is a human-readable description of the error.
• array<string>params
  is an array of character strings, indicating the object path to the request data parameters responsible for this error, if any.
• anyextra
  is used for additional error-specific data, but will be null in most cases.

Next steps

With these fundamentals, you're ready to start using the API to upload your data.