Sipfront API¶

Sipfront provides a REST API to programmatically control various aspects of the platform.

Data Format¶

The API responds with JSON data and standard HTTP response codes.

For requests that send a body, use Content-Type: application/json with a JSON object. The API still accepts form-encoded and multipart/form-data bodies on some endpoints for backward compatibility (for example, app image uploads and run parameter overrides).

Authentication¶

Authentication on the API is performed using Basic Authentication over HTTPS.

Info

You can create your own API key here: Sipfront API Keys.

Note

Note that the secret key is only revealed once, so if you lose it, you have to issue a new pair of keys.

REST Conventions¶

The Sipfront API v2 uses standard HTTP methods on resource paths:

Method	Use
`GET`	List or fetch a resource
`POST`	Create a resource, or trigger an action such as running a test
`PUT`	Update a resource
`DELETE`	Delete a resource

Examples of the RESTful style:

POST /tests/{id}/run — run a test
POST /projects/{id}/run — run a project
POST /targets — create a target
DELETE /targets/{id} — delete a target

Legacy RPC-style routes (verbs in the URL path, such as /create or /delete) remain available for backward compatibility but are deprecated. New integrations should use the RESTful routes.

OpenAPI Documentation¶

A machine-friendly OpenAPI specification of all endpoints is available at Sipfront API v2 Docs. The YAML file is at https://app.sipfront.com/apidocs/openapi.yaml.

Explore API Endpoints¶

AUTH="$public_key:$secret"
curl -X GET -u "$AUTH" https://app.sipfront.com/api/v2/ | jq .

The response lists all available API URLs with their supported HTTP methods:

{
  "endpoints": [
    {
      "methods": ["GET"],
      "url": "https://app.sipfront.com/api/v2"
    },
    {
      "methods": ["GET"],
      "url": "https://app.sipfront.com/api/v2/agentpools"
    },
    {
      "methods": ["GET", "POST"],
      "url": "https://app.sipfront.com/api/v2/appimages"
    },
    {
      "methods": ["GET"],
      "url": "https://app.sipfront.com/api/v2/callbacktemplates"
    },
    {
      "methods": ["GET", "POST"],
      "url": "https://app.sipfront.com/api/v2/credentials/pools"
    },
    {
      "methods": ["GET", "DELETE"],
      "url": "https://app.sipfront.com/api/v2/credentials/pools/:pid"
    },
    {
      "methods": ["POST"],
      "url": "https://app.sipfront.com/api/v2/credentials/pools/:pid/add"
    },
    {
      "methods": ["POST"],
      "url": "https://app.sipfront.com/api/v2/credentials/pools/:pid/delete"
    },
    {
      "methods": ["POST", "GET"],
      "url": "https://app.sipfront.com/api/v2/credentials/pools/:pid/entries"
    },
    {
      "methods": ["DELETE"],
      "url": "https://app.sipfront.com/api/v2/credentials/pools/:pid/entries/:id"
    },
    {
      "methods": ["GET"],
      "url": "https://app.sipfront.com/api/v2/credentials/pools/:pid/entries/:id/delete"
    },
    {
      "methods": ["POST"],
      "url": "https://app.sipfront.com/api/v2/credentials/pools/create"
    },
    {
      "methods": ["GET"],
      "url": "https://app.sipfront.com/api/v2/maintenance"
    },
    {
      "methods": ["DELETE", "GET", "PUT"],
      "url": "https://app.sipfront.com/api/v2/maintenance/:id"
    },
    {
      "methods": ["PUT"],
      "url": "https://app.sipfront.com/api/v2/maintenance/:id/stop"
    },
    {
      "methods": ["GET"],
      "url": "https://app.sipfront.com/api/v2/maintenance/active"
    },
    {
      "methods": ["POST"],
      "url": "https://app.sipfront.com/api/v2/maintenance/schedule"
    },
    {
      "methods": ["GET", "POST"],
      "url": "https://app.sipfront.com/api/v2/memory"
    },
    {
      "methods": ["GET", "DELETE"],
      "url": "https://app.sipfront.com/api/v2/memory/*key"
    },
    {
      "methods": ["GET", "POST"],
      "url": "https://app.sipfront.com/api/v2/projects"
    },
    {
      "methods": ["DELETE"],
      "url": "https://app.sipfront.com/api/v2/projects/:id"
    },
    {
      "methods": ["POST"],
      "url": "https://app.sipfront.com/api/v2/projects/:id/delete"
    },
    {
      "methods": ["POST"],
      "url": "https://app.sipfront.com/api/v2/projects/:id/run"
    },
    {
      "methods": ["GET"],
      "url": "https://app.sipfront.com/api/v2/projects/:id/status/last"
    },
    {
      "methods": ["GET"],
      "url": "https://app.sipfront.com/api/v2/projects/:pid/tests"
    },
    {
      "methods": ["POST"],
      "url": "https://app.sipfront.com/api/v2/projects/create"
    },
    {
      "methods": ["POST"],
      "url": "https://app.sipfront.com/api/v2/projects/run"
    },
    {
      "methods": ["GET"],
      "name": "api_projectrun_status",
      "url": "https://app.sipfront.com/api/v2/projects/run/:id/status"
    },
    {
      "methods": ["GET"],
      "url": "https://app.sipfront.com/api/v2/runs"
    },
    {
      "methods": ["GET"],
      "name": "api_run_status",
      "url": "https://app.sipfront.com/api/v2/runs/:id/status"
    },
    {
      "methods": ["GET", "POST"],
      "url": "https://app.sipfront.com/api/v2/runs/:sid/comments"
    },
    {
      "methods": ["GET"],
      "url": "https://app.sipfront.com/api/v2/runs/:sid/recordings"
    },
    {
      "methods": ["GET"],
      "url": "https://app.sipfront.com/api/v2/runs/:sid/siptrace/full"
    },
    {
      "methods": ["GET"],
      "url": "https://app.sipfront.com/api/v2/runs/:sid/siptrace/pcap"
    },
    {
      "methods": ["GET"],
      "url": "https://app.sipfront.com/api/v2/runs/:sid/siptrace/summary"
    },
    {
      "methods": ["GET"],
      "url": "https://app.sipfront.com/api/v2/runs/:sid/stats"
    },
    {
      "methods": ["GET"],
      "url": "https://app.sipfront.com/api/v2/runs/:sid/stats/:measure"
    },
    {
      "methods": ["GET", "POST"],
      "url": "https://app.sipfront.com/api/v2/targets"
    },
    {
      "methods": ["DELETE"],
      "url": "https://app.sipfront.com/api/v2/targets/:id"
    },
    {
      "methods": ["POST"],
      "url": "https://app.sipfront.com/api/v2/targets/:id/delete"
    },
    {
      "methods": ["POST"],
      "url": "https://app.sipfront.com/api/v2/targets/create"
    },
    {
      "methods": ["GET"],
      "url": "https://app.sipfront.com/api/v2/testbooks"
    },
    {
      "methods": ["GET"],
      "url": "https://app.sipfront.com/api/v2/testbooks/:id"
    },
    {
      "methods": ["GET"],
      "url": "https://app.sipfront.com/api/v2/testbooks/:id/full"
    },
    {
      "methods": ["GET", "POST"],
      "url": "https://app.sipfront.com/api/v2/tests"
    },
    {
      "methods": ["GET", "PUT", "DELETE"],
      "url": "https://app.sipfront.com/api/v2/tests/:id"
    },
    {
      "methods": ["POST"],
      "url": "https://app.sipfront.com/api/v2/tests/:id/run"
    },
    {
      "methods": ["GET"],
      "url": "https://app.sipfront.com/api/v2/tests/:id/status/last"
    },
    {
      "methods": ["GET"],
      "url": "https://app.sipfront.com/api/v2/tests/:tid/data"
    },
    {
      "methods": ["GET"],
      "url": "https://app.sipfront.com/api/v2/tests/:tid/dimensions"
    },
    {
      "methods": ["GET"],
      "url": "https://app.sipfront.com/api/v2/tests/:tid/results"
    },
    {
      "methods": ["GET"],
      "url": "https://app.sipfront.com/api/v2/tests/:tid/stats"
    },
    {
      "methods": ["GET"],
      "url": "https://app.sipfront.com/api/v2/tests/:tid/stats/:measure"
    },
    {
      "methods": ["POST"],
      "url": "https://app.sipfront.com/api/v2/tests/run"
    },
    {
      "methods": ["POST"],
      "url": "https://app.sipfront.com/api/v2/tests/scenarios/:apiname"
    },
    {
      "methods": ["GET"],
      "url": "https://app.sipfront.com/api/v2/testscenarios"
    }
  ],
  "status": 200
}

Explore available projects¶

AUTH="$public_key:$secret"
curl -X GET -u "$AUTH" https://app.sipfront.com/api/v2/projects | jq .

Explore available tests and their parameters¶

AUTH="$public_key:$secret"
curl -X GET -u "$AUTH" https://app.sipfront.com/api/v2/tests | jq .

Browse test sessions¶

AUTH="$public_key:$secret"
curl -X GET -u "$AUTH" https://app.sipfront.com/api/v2/runs | jq .

Below query parameters can be appended to the URL for pagination:

start: pagination offset
count: page size to fetch (defaults to 100)

Below query parameters can be appended to the URL for sorting:

orderby: sort by session column
- id
- session_id
- tags
- has_passed
- result_description
- test_id
- test_name
- project_id
- project_name
- started_at
- stopped_at
- agentpool_name
- is_finished
- is_failed
- testcase_name
- session_status
orderdir: sort direction
- asc
- desc

Below query parameters can be appended to the URL to narrow results by time range:

startdate: filter for runs started at after the specified timestamp in epoch seconds
enddate: filter for runs started at before the specified timestamp in epoch seconds

Below query parameters can be appended to the URL for detailed filtering:

filtername: filter by session column
- id
- session_id
- tags
- has_passed
- result_description
- test_id
- test_name
- project_id
- project_name
- started_at
- stopped_at
- agentpool_name
- is_finished
- is_failed
- testcase_name
- session_status
filterval: session column filter value

The filtername, filterval query parameters can be repeated to form conjunctions, ie. https://app.sipfront.com/api/v2/runs?filtername=tags&filterval=mytag1&filtername=tags&filterval=mytag2