{{label|upper}}: API Documentation (v{{version}})

INTRODUCTION

This documentation is intended to be a general overview of the {{label}} API. If you prefer, you can use Swagger/OpenAPI as alternative.

GENERAL NOTES

HTTP Transport & Methods

The HTTP is the transport method for accesing this API; all functions can be called using POST HTTP method; the functions that starts with get- in the name, can use GET HTTP method which in many cases benefits from the HTTP cache.

Authentication

The penpot backend right now offers two way for authenticate the request: cookies (the same mechanism that we use ourselves on accessing the API from the web application) and access tokens.

The cookie can be obtained using the `login-with-password` rpc method, on successful login it sets the `auth-token` cookie with the session token.

The access token can be obtained on the appropriate section on profile settings and it should be provided using `Authorization` header with `Token <token-string>` value.

Content Negotiation

This API operates indistinctly with: `application/json` and `application/transit+json` content types. You should specify the desired content-type on the `Accept` header, the transit encoding is used by default.

SSE (Server-Sent Events)

The methods marked with SSE returns a SSE formatted stream on the response body, always with status 200. The events are always encoded using `application/transit+json` encoding (for now no content negotiation is possible on methods that return SSE streams).

On the javascript side you can use the eventsoure-parser library for propertly parsing the response body using the standard Fetch API

Limits

The rate limit work per user basis (this means that different api keys share the same rate limit). For now the limits are not documented because we are studying and analyzing the data. As a general rule, it should not be abused, if an abusive use is detected, we will proceed to block the user's access to the API.

Webhooks

All methods that emit webhook events are marked with flag WEBHOOK, the data structure defined on each method represents the payload of the event.

The webhook event structure has this aspect:

{
  "id": "db601c95-045f-808b-8002-362f08fcb621",
  "name": "rename-file",
  "props": <payload>,
  "profileId": "db601c95-045f-808b-8002-361312e63531"
}