---
title: "REST API"
manual: "Interest"
version: "4.1"
source: "Implementing/Rest/Index.rst"
rendered: "2026-09-18T11:09:59+00:00"
---

# REST API {#implementing-rest}

-   [Basic request URL](#basic-request-url)
-   [Optional URL parts](#optional-url-parts)
-   [Authentication](#authentication)
-   [HTTP Methods](#http-methods)
-   [Optional HTTP Headers](#optional-http-headers)

## Basic request URL {#implementing-rest-basic}

Requests to the REST API usually follows a simple pattern, where all of the
parts, except from the endpoint, are optional or can be supplied elsewhere:

```text
http://www.example.org/[endpoint]/[table]/[remoteId]/[language]/[workspace]
```

Example with values added:

```text
http://www.example.org/rest/tt_content/Content-531/nb-NO/0
```

## Optional URL parts {#implementing-rest-optional-parts}

`[language]` and `[workspace]` are fully optional and can be left out entirely:

```text
http://www.example.org/[endpoint]/[table]/[remoteId]
```

They can also be supplied in the query string:

```text
http://www.example.org/[endpoint]/[table]/[remoteId]?language=[language]&workspace=[workspace]
```

## Authentication {#implementing-rest-authentication}

<!-- TODO: no Markdown rendering for "versionadded" -->

Since version 4.1, requests can be made with basic or basic
authentication. Previously, basic authentication was only available when
retrieving a bearer token through the authenticate endpoint.

### Security and performance considerations {#implementing-rest-authentication-security-performance}

`basic` authentication is *not as secure* and less performant than bearer
authentication. Because it requires you to encode and transmit your backend
username and password with every request, it offers inferior security.

`bearer` authentication is a token-based system where you first retrieve a
temporary token and then use only this token for subsequent requests.

### Scheme: `basic` {#implementing-rest-authentication-basic}

#### Generating your authentication string {#implementing-rest-authentication-basic-generating}

The `basic` HTTP authentication schema, uses a Base64-encoded string consisting
of a backend username and the corresponding password, separated by a colon: `:`.

Given the username "testuser" and password "test1234", the concatenated string
will be "testuser:test1234" and the Base64-encoded version:
"dGVzdHVzZXI6dGVzdDEyMzQ=".

You can base64-encode a string by using built-in terminal commands:

```bash
# Will output: dGVzdHVzZXI6dGVzdDEyMzQ=
echo -n "testuser:test1234" | base64
```

> [!WARNING]
> Using online tools for encoding your password is not advisable!

#### Using `basic` authentication in a request {#implementing-rest-authentication-basic-using}

Authentication is done using the `Authorization` HTTP header.

```bash
curl -XPOST \
     -H 'Authorization: basic dGVzdHVzZXI6dGVzdDEyMzQ=' \
     -v 'https://example.org/rest/pages/testPage' \
     -d '{"data":{"title":"Test Name","pid":"siteRootPage"}}'
```

The request will return a JSON response body:

```json
{"success":true,"message":"1 operation completed successfully."}
```

#### Fixing Apache and the authorization HTTP header {#implementing-rest-authentication-basic-apache}

When using Apache there is a need to add the following to .htaccess

```bash
RewriteEngine On
RewriteCond %{HTTP:Authorization} ^(.*)
RewriteRule .* - [e=HTTP_AUTHORIZATION:%1]
```

### Scheme: bearer (OAuth) {#implementing-rest-authentication-bearer}

#### Retrieving an authentication token {#implementing-rest-authentication-bearer-token}

When you use the `bearer` HTTP authentication scheme, you must first retrieve
an authentication token through the `authenticate` endpoint
using [\`basic\` authentication](#implementing-rest-authentication-basic).

```bash
curl -XPOST \
     -H 'Authorization: basic dGVzdHVzZXI6dGVzdDEyMzQ=' \
     -v 'https://example.org/rest/authenticate'
```

> [!NOTE]
> `authenticate` is a special endpoint used when retrieving a token. For
> obvious reasons, it only supports `basic` authentication.

This request will return a JSON response body including a token that can be
used on subsequent requests:

```json
{"success":true,"token":"f3c0946fb05aae4ad50897e9060ab4e8"}
```

#### Authenticating a request with a bearer token {#implementing-rest-authentication-bearer-authentication}

You supply the `bearer` token using the `Authorization` HTTP header in your
request:

```bash
curl -XPOST \
     -H 'Authorization: bearer f3c0946fb05aae4ad50897e9060ab4e8' \
     -v 'https://example.org/rest/pages/testPage' \
     -d '{"data":{"title":"Test Name","pid":"siteRootPage"}}'
```

## HTTP Methods {#implementing-rest-methods}

### POST {#implementing-rest-methods-post}

Create a record.

### PUT {#implementing-rest-methods-put}

Update a record.

### PATCH {#implementing-rest-methods-patch}

Update a record if it exists, otherwise create it.

### DELETE {#implementing-rest-methods-delete}

Delete a record.

```bash
curl -XDELETE \
     -H 'Authorization: bearer f3c0946fb05aae4ad50897e9060ab4e8' \
     -v 'https://example.org/rest/pages/testPage'
```

## Optional HTTP Headers {#optional-http-headers}

-   **Interest-Disable-Reference-Index**

    -   *Required:* false
    -   *Type:* Boolean

    Disable updating the reference index during the request. This has a positive
    performance impact. You can (and should) reindex the reference index manually
    afterwards.