> ## Documentation Index
> Fetch the complete documentation index at: https://upstash-vector.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Rest API

## Register Schema

`POST /subjects/$SUBJECT/versions?normalize=[true/false]`

Registers the schema under given `$SUBJECT` only if the new schema is [compatible](./schemacompatibility).

`normalize` is false by default. If passed, the schema will be normalized.
Normalization enables semantically same but syntactically different schemas to be accounted as the same schema.

```shell
curl https://tops-stingray-7863-eu1-rest-kafka.upstash.io/schema-registry/subjects/$SUBJECT/versions -u myuser:mypass -d '
{
  "schema": "{
    \"type\": \"record\",
    \"name\": \"myRecord\",
    \"fields\":
        [
        {\"type\": \"string\",\"name\": \"field1\"},
        {\"type\": \"int\"   ,\"name\": \"field2\"}
        ]
  }",
  "schemaType": "AVRO"
}'
```

**Success Response:**

The schema ID returned as the response:

```json
{"id" : 2}
```

**Fail Response:**

```
- 409 Conflict – Incompatible schema
- 422 Unprocessable Entity
  - Error code 42201 – Invalid schema
- 500 Internal Server Error
  - Error code 50001 – Error in the backend data store
  - Error code 50002 – Operation timed out
  - Error code 50003 – Error while forwarding the request to the primary
```

## Check schema

`POST /subjects/$SUBJECT?normalize=[true/false]&deleted=[true/false]`

Check if the given schema is registered under the `$SUBJECT`. Returns the schema along with subject, version, and schema type.

`normalize` is false by default. If set to `true`, the schema will be normalized.
Normalization enables semantically same but syntactically different schemas to be accounted as the same schema.

`deleted` is false by default. If set to `true`, the soft-deleted schemas under the subject will also be taken into account.
See [Delete Subject](#delete-subject) or [Delete Schema](#delete-schema) for details.

````shell
curl https://tops-stingray-7863-eu1-rest-kafka.upstash.io/schema-registry/my-subject/$SUBJECT -u myuser:mypass -d '
{
  "schema": "{
    \"type\": \"record\",
    \"name\": \"myRecord\",
    \"fields\":
        [
        {\"type\": \"string\",\"name\": \"field1\"},
        {\"type\": \"int\"   ,\"name\": \"field2\"}
        ]
  }",
  "schemaType": "AVRO"
}'

**Success Response:**

```json
{
      "subject": "my-subject",
      "id": 2
      "version": 3
      "schema":
         "
          {
            "schema": "{
              \"type\": \"record\",
              \"name\": \"myRecord\",
              \"fields\":
                  [
                  {\"type\": \"string\",\"name\": \"field1\"},
                  {\"type\": \"int\"   ,\"name\": \"field2\"}
                  ]
            }",
            "schemaType": "AVRO"
          }
         "
    }
````

**Fail Response**

```
- 404 Not Found
- Error code 40401 – Subject not found
- Error code 40403 – Schema not found
- 500 Internal Server Error
  - Error code 50001 – Error in the backend data store
  - Error code 50002 – Operation timed out
  - Error code 50003 – Error while forwarding the request to the primary
```

## Set Config

`PUT /config`

Sets the global compatibility. Global compatibility is effective if a subject is not assigned a compatibility by default.
See [Compatiblity](./schemacompatibility) for options.

```shell
curl -X PUT https://tops-stingray-7863-eu1-rest-kafka.upstash.io/schema-registry/config -u myuser:mypass -d '
{
  "compatibility" : "FULL"
}'
```

`PUT /config/$SUBJECT`

Sets the compatibility of a subject.
See [Compatiblity](./schemacompatibility) for options.

```shell
curl -X PUT https://tops-stingray-7863-eu1-rest-kafka.upstash.io/schema-registry/config/my-subject -u myuser:mypass -d '
{
  "compatibility" : "FULL"
}'
```

**Success Response:**

```json
{
  "compatibilityLevel" : "FULL"
}
```

**Fail Response**

```
- 500 Internal Server Error
    - Error code 50001 – Error in the backend data store
    - Error code 50002 – Operation timed out
    - Error code 50003 – Error while forwarding the request to the primary
```

## Get Config

`GET /config`

Retrieves the global config. Note that the default global config is `BACKWARD_TRANSITIVE` by default if not set.

```shell
curl https://tops-stingray-7863-eu1-rest-kafka.upstash.io/schema-registry/config -u myuser:mypass
```

`GET /config/$SUBJECT?defaultToGlobal=[true/false]`

Retrieves the config of the given `$SUBJECT`.

`defaultToGlobal` is false by default. When set to `true`, this endpoint will show the effective compatibility on a register
operation. When set to `false`, it may return 404 Not found if a subject level compatibility is not set.

```shell
curl https://tops-stingray-7863-eu1-rest-kafka.upstash.io/schema-registry/config/my-subject -u myuser:mypass
```

**Success Response:**

```json
{
  "compatibilityLevel" : "FULL"
}
```

**Fail Response**

```
- 404 Not Found – Subject not found
- 500 Internal Server Error
    - Error code 50001 – Error in the backend data store
    - Error code 50002 – Operation timed out
    - Error code 50003 – Error while forwarding the request to the primary
```

## Get All Schemas

`GET /schemas?deleted=[false/true]`

Returns all schemas registered under subjects. Note that this endpoint will return the same schema multiple times if the same schema registered
under different subjects.

`deleted` is false by default. If set to `true`, the soft-deleted schemas under the subject will also be taken into account.
See [Delete Subject](#delete-subject) or [Delete Schema](#delete-schema) for details.

```shell
curl https://tops-stingray-7863-eu1-rest-kafka.upstash.io/schema-registry/schemas -u myuser:mypass
```

**Success Response:**

```json
[
  {
    "subject": "subject1",
    "version": 1,
    "id": 1,
    "schemaType": "AVRO",
    "schema": "{\"type\":\"record\",\"name\":\"test\",\"fields\":[{\"name\":\"field1\",\"type\":\"string\"}]}"
  },
  {
    "subject": "subject2",
    "version": 1,
    "id": 2,
    "schemaType": "AVRO",
    "schema": "{\"type\":\"record\",\"name\":\"test\",\"fields\":[{\"name\":\"field1\",\"type\":\"string\"},{\"name\":\"field2\",\"type\":\"string\",\"default\":\"x\"}]}"
  }
]
```

**Fail Response**

```
- 500 Internal Server Error
  - Error code 50001 – Error in the backend data store
  - Error code 50002 – Operation timed out
  - Error code 50003 – Error while forwarding the request to the primary
```

## Get Schema With SchemaId

`GET /schemas/ids/$SCHEMA_ID`

Returns the schema corresponding to the given `$SCHEMA_ID`.

```shell
curl https://tops-stingray-7863-eu1-rest-kafka.upstash.io/schema-registry/schema/ids/1 -u myuser:mypass
```

**Success Response:**

```json
{
  "schema": "{\"type\":\"record\",\"name\":\"test\",\"fields\":[{\"name\":\"field1\",\"type\":\"string\"}]}"
}
```

**Fail Response**

```
- 404 Not Found
  - Error code 40403 – Schema not found
- 500 Internal Server Error
  - Error code 50001 – Error in the backend data store
  - Error code 50002 – Operation timed out
  - Error code 50003 – Error while forwarding the request to the primary
```

`GET /schemas/ids/$SCHEMA_ID/schema`

Returns the schema corresponding to the given `$SCHEMA_ID`. Additionally unwraps the inner schema field.

```shell
curl https://tops-stingray-7863-eu1-rest-kafka.upstash.io/schema-registry/schema/ids/1/schema -u myuser:mypass
```

**Success Response:**

```json
{
  "type": "record",
  "name": "test",
  "fields": [
    {
      "name": "field1",
      "type": "string"
    }
  ]
}
```

**Fail Response**

```
- 404 Not Found
  - Error code 40403 – Schema not found
- 500 Internal Server Error
  - Error code 50001 – Error in the backend data store
  - Error code 50002 – Operation timed out
  - Error code 50003 – Error while forwarding the request to the primary
```

## Get Schema With Subject And Version

`GET /subjects/$SUBJECT/versions/$VERSION?deleted=[true/false]`

Returns the schema with its metadata corresponding to the given `$SUBJECT` and `$VERSION`.
VERSION could be an int or string `latest`.

`deleted` is false by default. If set to `true`, the soft-deleted schemas under the subject will also be taken into account.
See [Delete Subject](#delete-subject) or [Delete Schema](#delete-schema) for details.

```shell
curl https://tops-stingray-7863-eu1-rest-kafka.upstash.io/schema-registry/subjects/subject1/versions/1 -u myuser:mypass
```

**Success Response:**

```json
{
  "subject": "s1",
  "version": 1,
  "id": 1,
  "schemaType": "AVRO",
  "schema": "{\"type\":\"record\",\"name\":\"test\",\"fields\":[{\"name\":\"field1\",\"type\":\"string\"}]}"
}
```

**Fail Response**

```
- 404 Not Found
  - Error code 40403 – Schema not found
- 500 Internal Server Error
  - Error code 50001 – Error in the backend data store
  - Error code 50002 – Operation timed out
  - Error code 50003 – Error while forwarding the request to the primary
```

`GET /subjects/$SUBJECT/versions/$VERSION?deleted=[true/false]`

Returns only the schema corresponding to the given `$SUBJECT` and `$VERSION`.
VERSION could be an int or string `latest`.

`deleted` is false by default. If set to `true`, the soft-deleted schemas under the subject will also be taken into account.
See [Delete Subject](#delete-subject) or [Delete Schema](#delete-schema) for details.

```shell
curl https://tops-stingray-7863-eu1-rest-kafka.upstash.io/schema-registry/subjects/subject1/versions/1/schema -u myuser:mypass
```

**Success Response:**

```json
{
  "type": "record",
  "name": "test",
  "fields": [
    {
      "name": "field1",
      "type": "string"
    }
  ]
}
```

**Fail Response**

```
- 404 Not Found
  - Error code 40401 – Subject not found
  - Error code 40402 – Version not found
- 422 Unprocessable Entity
  - Error code 42202 – Invalid version
- 500 Internal Server Error
  - Error code 50001 – Error in the backend data store
  - Error code 50002 – Operation timed out
  - Error code 50003 – Error while forwarding the request to the primary
```

## Get All Subjects

`GET /subjects?deleted=[false/true]`

Returns all subjects.

`deleted` is false by default. If set to `true`, the soft-deleted subjects will also be taken into account.
See [Delete Subject](#delete-subject) or [Delete Schema](#delete-schema) for details.

```shell
curl https://tops-stingray-7863-eu1-rest-kafka.upstash.io/schema-registry/subjects -u myuser:mypass
```

**Success Response:**

```json
["subject1","subject2"]
```

**Fail Response**

```
- 500 Internal Server Error
  - Error code 50001 – Error in the backend data store
  - Error code 50002 – Operation timed out
  - Error code 50003 – Error while forwarding the request to the primary
```

## Get Subject Versions

`GET /subjects/$SUBJECT/versions?deleted=[false/true]`

Returns the versions of the given `$SUBJECT`.

`deleted` is false by default. If set to `true`, the soft-deleted subject versions will also be taken into account.
See [Delete Subject](#delete-subject) or [Delete Schema](#delete-schema) for details.

```shell
curl https://tops-stingray-7863-eu1-rest-kafka.upstash.io/schema-registry/subjects/subject1/versions -u myuser:mypass
```

**Success Response:**

```json
[ 1, 2 ]
```

**Fail Response**

```
- 404 Not Found
  - Error code 40401 – Subject not found
- 500 Internal Server Error
  - Error code 50001 – Error in the backend data store
  - Error code 50002 – Operation timed out
  - Error code 50003 – Error while forwarding the request to the primary
```

## Delete Subject

`DELETE /subjects/$SUBJECT?permanent=[true/false]`

Deletes the given `$SUBJECT`. Returns the deleted versions as the response.

<Warning>
  This endpoint should rarely be needed in production and needs to be used with caution.
  The use-case for this endpoint is mostly cleaning up the resources after testing in development environments.
</Warning>

`permanent` is false by default. In this case, the subject only will be soft-deleted. The corresponding schemas and schema-ids
will not be deleted. Any serializer/deserializer needing these schemas still will be able to use them.

if `permanent` is set to true. The schemas and schema-ids will also be deleted from the system only if these schemas are not
registered under any other subjects. The schemas will be deleted only after the last related subject is permanently deleted.

Note that a subject can not be permanently deleted before it is soft-deleted.

```shell
curl -X DELETE https://tops-stingray-7863-eu1-rest-kafka.upstash.io/schema-registry/subjects/my-subject -u myuser:mypass
```

**Success Response:**

Returns the deleted versions as the response.

```json
[1, 2, 3]
```

**Fail Response:**

```
- 404 Not Found
  - Error code 40401 – Subject not found
  - Error code 40404 - Subject '$SUBJECT' was soft deleted. Set permanent=true to delete permanently
  - Error code 40405 - Subject '$SUBJECT' was not deleted first before being permanently deleted
- 422 Unprocessable Entity
  - Error code 42202 – Invalid version
- 500 Internal Server Error
  - Error code 50001 – Error in the backend data store
  - Error code 50002 – Operation timed out
  - Error code 50003 – Error while forwarding the request to the primary
```

## Delete Schema

`DELETE /subjects/$SUBJECT/versions/$VERSION?permanent=[true/false]`

Deletes the schema corresponding to the `$SUBJECT` and `$VERSION`. Returns the version as the response.
VERSION could be an int or string `latest`.

<Warning>
  This endpoint should rarely be needed in production and needs to be used with caution.
  The use-case for this endpoint is mostly cleaning up the resources after testing in development environments.
</Warning>

`permanent` is false by default. In this case, the subject-version only will be soft-deleted. The corresponding schema and schema-id
will not be deleted. Any serializer/deserializer needing this schema still will be able to use them.

if `permanent` is set to true. The schema and schema-id will also be deleted from the system only if this schema is not
registered under any other subjects. The schemas will be deleted only after the last related subject is permanently deleted.

Note that a subject-version can not be permanently deleted before it is soft-deleted.

```shell
curl -X DELETE https://tops-stingray-7863-eu1-rest-kafka.upstash.io/schema-registry/subjects/my-subject/versions/2 -u myuser:mypass
```

**Success Response:**

Returns the deleted version as the response.

```json
1
```

**Fail Response:**

```
- 404 Not Found
  - Error code 40401 – Subject not found
  - Error code 40402 – Version not found
  - Error code 40406 - Subject '$SUBJECT' Version $VERSION was soft deleted. Set permanent=true to delete permanently
  - Error code 40407 - Subject '$SUBJECT' Version $VERSION was not deleted first before being permanently deleted
- 422 Unprocessable Entity
  - Error code 42202 – Invalid version
- 500 Internal Server Error
  - Error code 50001 – Error in the backend data store
  - Error code 50002 – Operation timed out
  - Error code 50003 – Error while forwarding the request to the primary
```