Skip to main content

API Reference

Authentication​

Get an API key​

You can get an API key in the Heal.dev dashboard in the "Organization" menu. Click here to go directly to the page.

There you can create an API key, give it a name and copy it to your clipboard. You will not be able to see the key again, so make sure to store it in a safe place.

Use the API key​

All API calls made to the Heal.dev API must include the API key in the Authorization header. Here is an example of how to do it:

curl -X POST "https://api.heal.dev/api/projects/{{projectSlug}}/suites/{{suiteSlug}}/trigger" \
	-H "Authorization: Bearer {{your-api-key}}" \
	-H "Content-Type: application/json" \
	-d '{}'

Triggering a run​

To trigger a run, make a POST request on the endpoint /api/projects/:projectSlug/suites/:suiteSlug/trigger.

By default, or if the body is an empty JSON object, this will trigger all the stories in the suite.

curl -X POST "https://api.heal.dev/api/projects/{{projectSlug}}/suites/{{suiteSlug}}/trigger" \
	-H "Authorization: Bearer {{your-api-key}}" \
	-H "Content-Type: application/json" \
	-d '{}'

This endpoint will respond with a 201 status code and a JSON object with the following structure:

interface TriggerResponse {
    executionId: string;
    url: string;
}

The URL can be used to check the status of the run directly on the Heal.dev dashboard.

The endpoint accepts the following POST payload:

interface TriggerPayload {
    stories?: {
        slug: string;
        'test-config'?: {
            entrypoint?: string; // Should be a valid URL
            variables?: Record<string, string>;
        };
    }[];
    'test-config'?: {
        entrypoint?: string; // Should be a valid URL
        variables?: Record<string, string>;
    };
}

Changing the URL or variables of the stories​

Use the 'test-config' key to overwrite the base entrypoint or the variables of the stories.

curl -X POST "https://api.heal.dev/api/projects/{{projectSlug}}/suites/{{suiteSlug}}/trigger" \
	-H "Authorization: Bearer {{your-api-key}}" \
	-H "Content-Type: application/json" \
	-d '{"test-config":{"entrypoint":"https://pr-review-123.heal.dev","variables":{"foo":"bar"}}}'

Triggering specific stories​

Use the stories key to trigger specific stories with specific configurations:

curl -X POST "https://api.heal.dev/api/projects/{{projectSlug}}/suites/{{suiteSlug}}/trigger" \
	-H "Authorization: Bearer {{your-api-key}}" \
	-H "Content-Type: application/json" \
	-d '{"stories":[{"slug":"my-story","test-config":{"entrypoint":"https://pr-review-123.heal.dev","variables":{"foo":"bar"}}}]}'

You can use both keys at the same time, for instance, this will start only two stories with a specific base URL:

curl -X POST "https://api.heal.dev/api/projects/{{projectSlug}}/suites/{{suiteSlug}}/trigger" \
	-H "Authorization: Bearer {{your-api-key}}" \
	-H "Content-Type: application/json" \
	-d '{"stories":[{"slug":"story-1"},{"slug":"story-2"}],"test-config":{"entrypoint":"https://pr-review-123.heal.dev"}}'

Check the status of a run​

Using the executionId returned in the response of the trigger request, you can check the status of the run.

curl "https://api.heal.dev/api/execution/{{executionId}}" \
	-H "Authorization: Bearer {{your-api-key}}"

This will respond with a 200 status code and a JSON object with the following structure:

interface ExecutionResponse {
    projectName: string;
    suiteName: string;
    status: 'running' | 'finished',
    link: string;
    runs: {
        id: string;
        status: 'running' | 'finished';
        result?: 'PASS' | 'FAIL' | 'CRASH';
        variables: Record<string, string>;
        entrypoint: string;
        link: string;
    }
}