API address and environments

The Sursa API has its own address, separate from the address people use to open Sursa in the browser. All paths start with /v1.

Where Sursa runs	API address	This portal
Sursa cloud	`https://api.sursa.com`	`https://developers.sursa.com`
Your own installation	`https://api.<your domain>`, as set up by your administrator	`/developers/` on the API address
Your installation without a separate API address	the main address of the installation	`/developers/` on the main address

The API address only serves the API: there is no sign-in page, no cookies and no web interface on it. Every request is authenticated with an API key or an OAuth access token. The address can be served by several servers behind a load balancer; your integration does not need to know how many there are.

Integrations that call the API on the main address (for example https://app.sursa.com/v1) keep working. See Move to the API address for the few differences and a step-by-step move.

Base URL

Build every request from one base URL in your configuration, so the same code runs against any environment:

export SURSA_API="https://api.sursa.com"
curl "$SURSA_API/v1/me" -H "Authorization: Bearer $SURSA_API_KEY"

Use HTTPS only, and keep the key out of logs of the requests you make.

Version and specification

GET /v1/health tells whether the address is up and returns the version of Sursa that serves it. It answers without a key, so you can use it in monitoring:

curl https://api.example.com/v1/health

{"ok": true, "version": "v1.4.0"}

This is the version of the Sursa release, not of the API. The version of the API is info.version of its specification. The OpenAPI 3.1 specification of the API is published at the same address, without authentication:

Path	Content
`GET /openapi.json`	The public specification, with this address in `servers`.
`GET /v1/openapi-public.json`	The same specification. Supports `ETag` and `If-None-Match`.

Use it to generate a client, to import the API into a tool such as Postman, or to check in CI that your integration only uses operations of the version you expect. The API reference of this portal is built from the same file.

Testing

Sursa has no separate test mode: every request with a key acts on the real data of its organization. To develop and test safely:

Create a separate key for development with the narrowest role and scopes that the work needs.
Write into a dedicated collection, for example sandbox, that only your team can see, and delete it when you are done.
If your company has a separate Sursa organization or installation for testing, point the base URL and the key at it. Nothing else in your code changes.
Make retries safe from the start: send an Idempotency-Key with every POST and PATCH.

The Try it console on each endpoint page of the API reference sends real requests with a key that you paste into it. The key stays in the memory of the browser tab and is sent only to the API address.

Network requirements

Outgoing HTTPS (port 443) from your servers to the API address.
Allow the host name rather than fixed IP addresses in firewall rules where your network allows it: the servers behind the address can change as capacity is added.
Browser applications can call the API directly: responses allow any origin (Access-Control-Allow-Origin: *) without cookies. Keep in mind that a key used in a browser is visible to the user of that browser.