Introduction

The API is the programmatic way of interfacing with the Brossa server.

Please contact help@artificial.io if you have any questions, feedback or issues.

Base URL

The Base URL is the same as you might use to access the Brossa UI in a given environment, with the API suffix api/external/public:

https://<organisation>-<env>.artificial.app/api/external/public

For example:

<!-- Production URL -->
https://artificial.artificial.app/api/external/public

<!-- UAT URL -->
https://artificial-uat.artificial.app/api/external/public

Authentication

This API uses the OAuth2 protocol via Okta or Auth0 to authenticate requests. Only users with the role Underwriter or above are authorised to access the API.

For machine-to-machine authorisation, you will need to:

  • 1. Request a client ID and secret from the team at help@artificial.io

  • 2. Acquire an access token using the client ID and client secret

  • 3. Use the token to access the Brossa API

To verify the above process manually:

Acquire an access token

$ curl --request POST \
    --header 'Content-Type: application/json' \
    --url https://auth.artificialos.com/oauth/token \
    --data "{\"client_id\":$CLIENT_ID,\"client_secret\":$CLIENT_SECRET,\"audience\":\"https://<organisation>-<env>.artificial.app\",\"grant_type\":\"client_credentials\"}"

# {"access_token":"$ACCESS_TOKEN","expires_in":86400,"token_type":"Bearer"}

Use the access token

$ curl --header 'Content-Type: application/json' \
    --header "Authorization: Bearer $ACCESS_TOKEN" \
    https://<organisation>-<env>.artificial.app/api/user/me

# {"displayName": "...","email":"...","id":"...","nanoId":"...","org":n,"role":"underwriter","source":"Auth0"}

Pagination

Paginated responses in this API, for example Policies, use cursors to traverse through a paginated data set. The cursor represents a specific position in the data set.

Request a page of up to 100 items by providing the page_limit query parameter. For example:

GET /policies?page_limit=100

If no page_limit is specified, the default page limit is 20.

Request pages in sequence by referencing the next_cursor value in each response. For example:

Request page 1: first 100 policies

GET /policies?page_limit=100

Response page 1: first 100 policies

{
    "next_cursor": 2, # numeric cursor used to request the next page
    "next_cursor_url": "https://<organisation>.artificial.io/api/external/public/policies?page_limit=100&page_cursor=2", # helper URL to request the next page
    "items": [...] # array of the first 100 Policy objects
}

Request page 2: next 100 policies

GET /policies?page_limit=100&page_cursor=2

Response page 2: next 100 policies

{
    "next_cursor": 3, # cursor used to request the next page
    "next_cursor_url": "https://<organisation>.artificial.io/api/external/public/policies?page_limit=100&page_cursor=3", # helper URL to request the next page
    "items": [...] # array of the next 100 Policy objects
}

Versioning

This API follows the Parallel Change approach to versioning. This means that:

  • existing endpoints do not change

  • new features or backwards-incompatible changes are introduced via new, versioned, endpoints

  • API clients can access new functionality by calling the latest endpoint version

Versions