# REST API

Shlink provides a REST API that can be used to integrate the short URLs management on any consuming system or application.

This document explains the behavior of some aspects and architectural decisions of the API.


### Content negotiation {#content-negotiation}


All the requests return JSON-encoded responses by default, together with semantic status codes, so it should be easy to implement client apps that consume this API.

However, if an unexpected error occurs, the system could end up returning HTML. To prevent this, always pass the header `Accept: application/json`.


### CORS {#cors}


This API supports [**C**ross-**O**rigin **R**esource **S**haring](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing) out of the box (aka cross domain).

It will automatically generate the required `Access-Control-*` headers and manage pre-flight (`OPTIONS`) requests, so it can be transparently consumed from web clients hosted on different domains.

Starting with Shlink v2.5.2, the `Access-Control-Allow-Origin` header will be returned with value `*`. Previous versions used to return the value coming in the request's `Origin` header instead, but some browsers might not accept that value when it's an IP address, therefore the change.

**Important:** notice that Shlink will not generate the CORS headers when the request does not include an `Origin` header, in which case it will consider the request a server-to-server one. Browsers will always send this header when consuming an API on a different domain, so it should work transparently.


### Dates {#dates}


The API tries to be consistent on how dates are handled and exchanged, but these are some basic guidelines:

- All returned dates will have the [ISO-8601](https://en.wikipedia.org/wiki/ISO_8601) format with offset from UTC (for example, `2020-01-23T05:16:00+02:00`).
- Any endpoint accepting dates will also expect the same format, usually resulting in `400 Bad Request` response when this is not fulfilled.
- Shlink also assumes all persisted dates (from visits, short URL creation, etc) belong to the timezone in which Shlink is configured.
- Any input date will be converted to the timezone in which Shlink is configured, before using it to query data.
  - For example, if Shlink is configured in `America/Los_Angeles`, and the date `2020-01-23T05:16:00+02:00` is provided as part of the input for any endpoint, Shlink will first cast it to `2020-01-22T19:16:00-08:00`.


### Request tracing {#request-tracing}


Shlink generates a request ID on every API request. This ID is returned inside the `X-Request-Id` response header, and can be used to identify all the logs generated by Shlink during that request, as they are all prefixed with this ID.

If you use Shlink as part of a collection of services and need to be able to trace the whole request flow, you can also send the same `X-Request-Id` header in the request, and Shlink will use that value instead of generating a new one.


### Further information {#further-information}


Continue reading the rest of the sections to understand more details of the API.





- [Authentication](https://sourcey-shlink.pages.dev/documentation/api-docs/authentication/index.md)
- [Error management](https://sourcey-shlink.pages.dev/documentation/api-docs/error-management/index.md)
- [API key roles](https://sourcey-shlink.pages.dev/documentation/api-docs/api-key-roles/index.md)