# Versioning service

This is the external-facing portion of VersioningService which gives clients access to functionality that doesn’t create new commits. The creation of new commits should be done via the resource-specific services.

OpenAPI file: [`VersioningService.json`](https://dev.nominal.io/api/_downloads/b55fbacc50e6b3369f5fa9cd32ff5047/VersioningService.json)

## Endpoints

### Create branch

POST `/scout/v1/versioning/{resourceRid}/branch`

Creates a mutable pointer to the provided commit. “Saves”/”commits” can be performed on this pointer. Throws if the name is already used as a commit pointer for this resource. Throws if the provided commit doesn’t exist.

Path parameters

`resourceRid` string (RID) required
:   ​

Body

`existingCommit` string required
:   ​

`branchName` string required
:   ​

Response

`rid` string (RID)
:   ​

`name` string
:   ​

`resourceRid` string (RID)
:   ​

`commit` string
:   ​

`createdBy` string (RID)
:   ​

`createdAt` string (date-time)
:   ​

`updatedAt` string (date-time)
:   ​

Request

**curl**

```shell
curl -X POST "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/branch" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "existingCommit": "<commit id>",
  "branchName": "<branch name>"
}'
```

**requests**

```python
import requests

response = requests.post(
    "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/branch",
    headers={"Authorization": "Bearer <api key>"},
    json={"existingCommit": "<commit id>", "branchName": "<branch name>"},
)
response.raise_for_status()
print(response.json())
```

**httpx**

```python
import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/branch",
    headers={"Authorization": "Bearer <api key>"},
    json={"existingCommit": "<commit id>", "branchName": "<branch name>"},
)
response.raise_for_status()
print(response.json())
```

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/branch",
            headers={"Authorization": "Bearer <api key>"},
            json={"existingCommit": "<commit id>", "branchName": "<branch name>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())

asyncio.run(main())
```

Response: `200`

```json
{
  "rid": "<branch rid>",
  "name": "<branch name>",
  "resourceRid": "<resource rid>",
  "commit": "<commit id>",
  "createdBy": "<user rid>",
  "createdAt": "2026-01-01T00:00:00Z",
  "updatedAt": "2026-01-01T00:00:00Z"
}
```

### Get branches

GET `/scout/v1/versioning/{resourceRid}/branch`

Returns all branches for the resource in order of most recently updated.

Path parameters

`resourceRid` string (RID) required
:   ​

Response

The body is an array of [`Branch`](https://dev.nominal.io/api/rest/versioning-service.md#branch).

Fields of `Branch`

`rid` string (RID)
:   ​

`name` string
:   ​

`resourceRid` string (RID)
:   ​

`commit` string
:   ​

`createdBy` string (RID)
:   ​

`createdAt` string (date-time)
:   ​

`updatedAt` string (date-time)
:   ​

Request

**curl**

```shell
curl "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/branch" \
  -H "Authorization: Bearer <api key>"
```

**requests**

```python
import requests

response = requests.get(
    "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/branch",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())
```

**httpx**

```python
import httpx

response = httpx.get(
    "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/branch",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())
```

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.get(
            "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/branch",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())

asyncio.run(main())
```

Response: `200`

```json
[
  {
    "rid": "<branch rid>",
    "name": "<branch name>",
    "resourceRid": "<resource rid>",
    "commit": "<commit id>",
    "createdBy": "<user rid>",
    "createdAt": "2026-01-01T00:00:00Z",
    "updatedAt": "2026-01-01T00:00:00Z"
  }
]
```

### Create tag

POST `/scout/v1/versioning/{resourceRid}/tag`

Creates an immutable pointer to the provided commit. Throws if the name is already used as a commit pointer for this resource. Throws if the provided commit doesn’t exist.

Path parameters

`resourceRid` string (RID) required
:   ​

Body

`existingCommit` string required
:   ​

`tagName` string required
:   ​

Response

`rid` string (RID)
:   ​

`name` string
:   ​

`resourceRid` string (RID)
:   ​

`commit` string
:   ​

`createdBy` string (RID)
:   ​

`createdAt` string (date-time)
:   ​

Request

**curl**

```shell
curl -X POST "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/tag" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "existingCommit": "<commit id>",
  "tagName": "<tag name>"
}'
```

**requests**

```python
import requests

response = requests.post(
    "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/tag",
    headers={"Authorization": "Bearer <api key>"},
    json={"existingCommit": "<commit id>", "tagName": "<tag name>"},
)
response.raise_for_status()
print(response.json())
```

**httpx**

```python
import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/tag",
    headers={"Authorization": "Bearer <api key>"},
    json={"existingCommit": "<commit id>", "tagName": "<tag name>"},
)
response.raise_for_status()
print(response.json())
```

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/tag",
            headers={"Authorization": "Bearer <api key>"},
            json={"existingCommit": "<commit id>", "tagName": "<tag name>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())

asyncio.run(main())
```

Response: `200`

```json
{
  "rid": "<tag rid>",
  "name": "<tag name>",
  "resourceRid": "<resource rid>",
  "commit": "<commit id>",
  "createdBy": "<user rid>",
  "createdAt": "2026-01-01T00:00:00Z"
}
```

### Get tags by resource

GET `/scout/v1/versioning/{resourceRid}/tag`

Returns all tags for the resource in order of most recently created.

Path parameters

`resourceRid` string (RID) required
:   ​

Response

The body is an array of [`Tag`](https://dev.nominal.io/api/rest/versioning-service.md#tag).

Fields of `Tag`

`rid` string (RID)
:   ​

`name` string
:   ​

`resourceRid` string (RID)
:   ​

`commit` string
:   ​

`createdBy` string (RID)
:   ​

`createdAt` string (date-time)
:   ​

Request

**curl**

```shell
curl "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/tag" \
  -H "Authorization: Bearer <api key>"
```

**requests**

```python
import requests

response = requests.get(
    "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/tag",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())
```

**httpx**

```python
import httpx

response = httpx.get(
    "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/tag",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())
```

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.get(
            "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/tag",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())

asyncio.run(main())
```

Response: `200`

```json
[
  {
    "rid": "<tag rid>",
    "name": "<tag name>",
    "resourceRid": "<resource rid>",
    "commit": "<commit id>",
    "createdBy": "<user rid>",
    "createdAt": "2026-01-01T00:00:00Z"
  }
]
```

### Get commit

GET `/scout/v1/versioning/{resourceRid}/commit/{commitId}`

Throws if the commit doesn’t exist.

Path parameters

`resourceRid` string (RID) required
:   ​

`commitId` string required
:   ​

Response

`id` string
:   ​

`resourceRid` string (RID)
:   ​

`parentCommit` string
:   ​

`mergeParentCommit` string
:   ​

`message` string
:   ​

`isWorkingState` boolean
:   A working state commit is created via the `saveWorkingState` endpoint and is non-permanent. In the future, it may be compacted and not exist.

`committedBy` string (RID)
:   ​

`committedAt` string (date-time)
:   ​

Request

**curl**

```shell
curl "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/commit/<commit id>" \
  -H "Authorization: Bearer <api key>"
```

**requests**

```python
import requests

response = requests.get(
    "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/commit/<commit id>",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())
```

**httpx**

```python
import httpx

response = httpx.get(
    "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/commit/<commit id>",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())
```

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.get(
            "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/commit/<commit id>",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())

asyncio.run(main())
```

Response: `200`

```json
{
  "id": "<commit id>",
  "resourceRid": "<resource rid>",
  "parentCommit": "<commit id>",
  "mergeParentCommit": "<commit id>",
  "message": "<message>",
  "isWorkingState": true,
  "committedBy": "<user rid>",
  "committedAt": "2026-01-01T00:00:00Z"
}
```

### Batch get commits

POST `/scout/v1/versioning/commit/batch-get`

Filters out resources that are not authorized.

Body

The body is an array of [`ResourceAndCommitId`](https://dev.nominal.io/api/rest/versioning-service.md#resourceandcommitid).

Fields of `ResourceAndCommitId`

`resourceRid` string (RID) required
:   ​

`commitId` string required
:   ​

Response

The body is an array of [`Commit`](https://dev.nominal.io/api/rest/versioning-service.md#commit).

Fields of `Commit`

`id` string
:   ​

`resourceRid` string (RID)
:   ​

`parentCommit` string
:   ​

`mergeParentCommit` string
:   ​

`message` string
:   ​

`isWorkingState` boolean
:   A working state commit is created via the `saveWorkingState` endpoint and is non-permanent. In the future, it may be compacted and not exist.

`committedBy` string (RID)
:   ​

`committedAt` string (date-time)
:   ​

Request

**curl**

```shell
curl -X POST "https://api.gov.nominal.io/api/scout/v1/versioning/commit/batch-get" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '[
  {
    "resourceRid": "<resource rid>",
    "commitId": "<commit id>"
  }
]'
```

**requests**

```python
import requests

response = requests.post(
    "https://api.gov.nominal.io/api/scout/v1/versioning/commit/batch-get",
    headers={"Authorization": "Bearer <api key>"},
    json=[{"resourceRid": "<resource rid>", "commitId": "<commit id>"}],
)
response.raise_for_status()
print(response.json())
```

**httpx**

```python
import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/scout/v1/versioning/commit/batch-get",
    headers={"Authorization": "Bearer <api key>"},
    json=[{"resourceRid": "<resource rid>", "commitId": "<commit id>"}],
)
response.raise_for_status()
print(response.json())
```

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/scout/v1/versioning/commit/batch-get",
            headers={"Authorization": "Bearer <api key>"},
            json=[{"resourceRid": "<resource rid>", "commitId": "<commit id>"}],
        ) as response:
            response.raise_for_status()
            print(await response.json())

asyncio.run(main())
```

Response: `200`

```json
[
  {
    "id": "<commit id>",
    "resourceRid": "<resource rid>",
    "parentCommit": "<commit id>",
    "mergeParentCommit": "<commit id>",
    "message": "<message>",
    "isWorkingState": true,
    "committedBy": "<user rid>",
    "committedAt": "2026-01-01T00:00:00Z"
  }
]
```

### Get commit by branch

GET `/scout/v1/versioning/{resourceRid}/branch/{branchName}/commit`

Returns the commit pointed to by the branch. Throws if the branch doesn’t exist.

Path parameters

`resourceRid` string (RID) required
:   ​

`branchName` string required
:   ​

Response

`id` string
:   ​

`resourceRid` string (RID)
:   ​

`parentCommit` string
:   ​

`mergeParentCommit` string
:   ​

`message` string
:   ​

`isWorkingState` boolean
:   A working state commit is created via the `saveWorkingState` endpoint and is non-permanent. In the future, it may be compacted and not exist.

`committedBy` string (RID)
:   ​

`committedAt` string (date-time)
:   ​

Request

**curl**

```shell
curl "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/branch/<branch name>/commit" \
  -H "Authorization: Bearer <api key>"
```

**requests**

```python
import requests

response = requests.get(
    "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/branch/<branch name>/commit",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())
```

**httpx**

```python
import httpx

response = httpx.get(
    "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/branch/<branch name>/commit",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())
```

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.get(
            "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/branch/<branch name>/commit",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())

asyncio.run(main())
```

Response: `200`

```json
{
  "id": "<commit id>",
  "resourceRid": "<resource rid>",
  "parentCommit": "<commit id>",
  "mergeParentCommit": "<commit id>",
  "message": "<message>",
  "isWorkingState": true,
  "committedBy": "<user rid>",
  "committedAt": "2026-01-01T00:00:00Z"
}
```

### Get commit by tag

GET `/scout/v1/versioning/{resourceRid}/tag/{tagName}/commit`

Returns the commit pointed to by the tag. Throws if the tag doesn’t exist.

Path parameters

`resourceRid` string (RID) required
:   ​

`tagName` string required
:   ​

Response

`id` string
:   ​

`resourceRid` string (RID)
:   ​

`parentCommit` string
:   ​

`mergeParentCommit` string
:   ​

`message` string
:   ​

`isWorkingState` boolean
:   A working state commit is created via the `saveWorkingState` endpoint and is non-permanent. In the future, it may be compacted and not exist.

`committedBy` string (RID)
:   ​

`committedAt` string (date-time)
:   ​

Request

**curl**

```shell
curl "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/tag/<tag name>/commit" \
  -H "Authorization: Bearer <api key>"
```

**requests**

```python
import requests

response = requests.get(
    "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/tag/<tag name>/commit",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())
```

**httpx**

```python
import httpx

response = httpx.get(
    "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/tag/<tag name>/commit",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())
```

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.get(
            "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/tag/<tag name>/commit",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())

asyncio.run(main())
```

Response: `200`

```json
{
  "id": "<commit id>",
  "resourceRid": "<resource rid>",
  "parentCommit": "<commit id>",
  "mergeParentCommit": "<commit id>",
  "message": "<message>",
  "isWorkingState": true,
  "committedBy": "<user rid>",
  "committedAt": "2026-01-01T00:00:00Z"
}
```

### Get least common ancestor

POST `/scout/v1/versioning/{resourceRid}/commit/least-common-ancestor`

Returns the least common ancestor of the two commits. Throws if either commit doesn’t exist.

Path parameters

`resourceRid` string (RID) required
:   ​

Body

`commit1` string required
:   ​

`commit2` string required
:   ​

Response

The body is a string.

Request

**curl**

```shell
curl -X POST "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/commit/least-common-ancestor" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '{
  "commit1": "<commit id>",
  "commit2": "<commit id>"
}'
```

**requests**

```python
import requests

response = requests.post(
    "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/commit/least-common-ancestor",
    headers={"Authorization": "Bearer <api key>"},
    json={"commit1": "<commit id>", "commit2": "<commit id>"},
)
response.raise_for_status()
print(response.json())
```

**httpx**

```python
import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/commit/least-common-ancestor",
    headers={"Authorization": "Bearer <api key>"},
    json={"commit1": "<commit id>", "commit2": "<commit id>"},
)
response.raise_for_status()
print(response.json())
```

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/commit/least-common-ancestor",
            headers={"Authorization": "Bearer <api key>"},
            json={"commit1": "<commit id>", "commit2": "<commit id>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())

asyncio.run(main())
```

Response: `200`

```json
"<commit id>"
```

### Get commit history

GET `/scout/v1/versioning/{resourceRid}/commit/{commitId}/history`

Returns the commit history sorted by creation time descending. Excludes working state commits unless includeWorkingState is true. Throws if the commit doesn’t exist.

Path parameters

`resourceRid` string (RID) required
:   ​

`commitId` string required
:   ​

Query parameters

`pageSize` integer
:   Defaults to 100, throws if larger than 1000.

`nextPageToken` string
:   ​

`includeWorkingState` boolean
:   When true, include working-state (compactible) commits in the history. Defaults to false. Working-state commits may later be compacted and cease to exist.

Response

`history` array of [`Commit`](https://dev.nominal.io/api/rest/versioning-service.md#commit)
:   ​

    Fields of `Commit`

    `id` string
    :   ​

    `resourceRid` string (RID)
    :   ​

    `parentCommit` string
    :   ​

    `mergeParentCommit` string
    :   ​

    `message` string
    :   ​

    `isWorkingState` boolean
    :   A working state commit is created via the `saveWorkingState` endpoint and is non-permanent. In the future, it may be compacted and not exist.

    `committedBy` string (RID)
    :   ​

    `committedAt` string (date-time)
    :   ​

`nextPageToken` string
:   ​

Request

**curl**

```shell
curl "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/commit/<commit id>/history" \
  -H "Authorization: Bearer <api key>"
```

**requests**

```python
import requests

response = requests.get(
    "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/commit/<commit id>/history",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())
```

**httpx**

```python
import httpx

response = httpx.get(
    "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/commit/<commit id>/history",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())
```

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.get(
            "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/commit/<commit id>/history",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())

asyncio.run(main())
```

Response: `200`

```json
{
  "history": [
    {
      "id": "<commit id>",
      "resourceRid": "<resource rid>",
      "parentCommit": "<commit id>",
      "mergeParentCommit": "<commit id>",
      "message": "<message>",
      "isWorkingState": true,
      "committedBy": "<user rid>",
      "committedAt": "2026-01-01T00:00:00Z"
    }
  ],
  "nextPageToken": "<token>"
}
```

### Persist commits

POST `/scout/v1/versioning/commit/persist`

Persists the commits so that they are not compacted. This operation is atomic - either all commits are persisted or none are (in the case of an error).

Body

The body is an array of [`ResourceAndCommitId`](https://dev.nominal.io/api/rest/versioning-service.md#resourceandcommitid).

Fields of `ResourceAndCommitId`

`resourceRid` string (RID) required
:   ​

`commitId` string required
:   ​

Response

No content (HTTP 204).

Request

**curl**

```shell
curl -X POST "https://api.gov.nominal.io/api/scout/v1/versioning/commit/persist" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '[
  {
    "resourceRid": "<resource rid>",
    "commitId": "<commit id>"
  }
]'
```

**requests**

```python
import requests

response = requests.post(
    "https://api.gov.nominal.io/api/scout/v1/versioning/commit/persist",
    headers={"Authorization": "Bearer <api key>"},
    json=[{"resourceRid": "<resource rid>", "commitId": "<commit id>"}],
)
response.raise_for_status()
```

**httpx**

```python
import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/scout/v1/versioning/commit/persist",
    headers={"Authorization": "Bearer <api key>"},
    json=[{"resourceRid": "<resource rid>", "commitId": "<commit id>"}],
)
response.raise_for_status()
```

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/scout/v1/versioning/commit/persist",
            headers={"Authorization": "Bearer <api key>"},
            json=[{"resourceRid": "<resource rid>", "commitId": "<commit id>"}],
        ) as response:
            response.raise_for_status()

asyncio.run(main())
```

Response: `204`

No content.

### Get branch

GET `/scout/v1/versioning/{resourceRid}/branch/{branchName}`

Throws if the branch doesn’t exist.

Path parameters

`resourceRid` string (RID) required
:   ​

`branchName` string required
:   ​

Response

`rid` string (RID)
:   ​

`name` string
:   ​

`resourceRid` string (RID)
:   ​

`commit` string
:   ​

`createdBy` string (RID)
:   ​

`createdAt` string (date-time)
:   ​

`updatedAt` string (date-time)
:   ​

Request

**curl**

```shell
curl "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/branch/<branch name>" \
  -H "Authorization: Bearer <api key>"
```

**requests**

```python
import requests

response = requests.get(
    "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/branch/<branch name>",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())
```

**httpx**

```python
import httpx

response = httpx.get(
    "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/branch/<branch name>",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())
```

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.get(
            "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/branch/<branch name>",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())

asyncio.run(main())
```

Response: `200`

```json
{
  "rid": "<branch rid>",
  "name": "<branch name>",
  "resourceRid": "<resource rid>",
  "commit": "<commit id>",
  "createdBy": "<user rid>",
  "createdAt": "2026-01-01T00:00:00Z",
  "updatedAt": "2026-01-01T00:00:00Z"
}
```

### Delete branch

DELETE `/scout/v1/versioning/{resourceRid}/branch/{branchName}`

Deletes the branch pointer. Throws if the branch doesn’t exist. Throws if you attempt to delete the “main” branch.

Path parameters

`resourceRid` string (RID) required
:   ​

`branchName` string required
:   ​

Response

No content (HTTP 204).

Request

**curl**

```shell
curl -X DELETE "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/branch/<branch name>" \
  -H "Authorization: Bearer <api key>"
```

**requests**

```python
import requests

response = requests.delete(
    "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/branch/<branch name>",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
```

**httpx**

```python
import httpx

response = httpx.delete(
    "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/branch/<branch name>",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
```

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.delete(
            "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/branch/<branch name>",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()

asyncio.run(main())
```

Response: `204`

No content.

### Batch get branches

POST `/scout/v1/versioning/branch/batch-get`

Omits branches that are not authorized.

Body

The body is an array of [`ResourceAndBranchName`](https://dev.nominal.io/api/rest/versioning-service.md#resourceandbranchname).

Fields of `ResourceAndBranchName`

`resourceRid` string (RID) required
:   ​

`branchName` string required
:   ​

Response

The body is an array of [`Branch`](https://dev.nominal.io/api/rest/versioning-service.md#branch).

Fields of `Branch`

`rid` string (RID)
:   ​

`name` string
:   ​

`resourceRid` string (RID)
:   ​

`commit` string
:   ​

`createdBy` string (RID)
:   ​

`createdAt` string (date-time)
:   ​

`updatedAt` string (date-time)
:   ​

Request

**curl**

```shell
curl -X POST "https://api.gov.nominal.io/api/scout/v1/versioning/branch/batch-get" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '[
  {
    "resourceRid": "<resource rid>",
    "branchName": "<branch name>"
  }
]'
```

**requests**

```python
import requests

response = requests.post(
    "https://api.gov.nominal.io/api/scout/v1/versioning/branch/batch-get",
    headers={"Authorization": "Bearer <api key>"},
    json=[{"resourceRid": "<resource rid>", "branchName": "<branch name>"}],
)
response.raise_for_status()
print(response.json())
```

**httpx**

```python
import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/scout/v1/versioning/branch/batch-get",
    headers={"Authorization": "Bearer <api key>"},
    json=[{"resourceRid": "<resource rid>", "branchName": "<branch name>"}],
)
response.raise_for_status()
print(response.json())
```

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/scout/v1/versioning/branch/batch-get",
            headers={"Authorization": "Bearer <api key>"},
            json=[{"resourceRid": "<resource rid>", "branchName": "<branch name>"}],
        ) as response:
            response.raise_for_status()
            print(await response.json())

asyncio.run(main())
```

Response: `200`

```json
[
  {
    "rid": "<branch rid>",
    "name": "<branch name>",
    "resourceRid": "<resource rid>",
    "commit": "<commit id>",
    "createdBy": "<user rid>",
    "createdAt": "2026-01-01T00:00:00Z",
    "updatedAt": "2026-01-01T00:00:00Z"
  }
]
```

### Get tag

GET `/scout/v1/versioning/{resourceRid}/tag/{tagName}`

Throws if the tag doesn’t exist.

Path parameters

`resourceRid` string (RID) required
:   ​

`tagName` string required
:   ​

Response

`rid` string (RID)
:   ​

`name` string
:   ​

`resourceRid` string (RID)
:   ​

`commit` string
:   ​

`createdBy` string (RID)
:   ​

`createdAt` string (date-time)
:   ​

Request

**curl**

```shell
curl "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/tag/<tag name>" \
  -H "Authorization: Bearer <api key>"
```

**requests**

```python
import requests

response = requests.get(
    "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/tag/<tag name>",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())
```

**httpx**

```python
import httpx

response = httpx.get(
    "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/tag/<tag name>",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
print(response.json())
```

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.get(
            "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/tag/<tag name>",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()
            print(await response.json())

asyncio.run(main())
```

Response: `200`

```json
{
  "rid": "<tag rid>",
  "name": "<tag name>",
  "resourceRid": "<resource rid>",
  "commit": "<commit id>",
  "createdBy": "<user rid>",
  "createdAt": "2026-01-01T00:00:00Z"
}
```

### Delete tag

DELETE `/scout/v1/versioning/{resourceRid}/tag/{tagName}`

Deletes the tag pointer. Throws if the tag doesn’t exist.

Path parameters

`resourceRid` string (RID) required
:   ​

`tagName` string required
:   ​

Response

No content (HTTP 204).

Request

**curl**

```shell
curl -X DELETE "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/tag/<tag name>" \
  -H "Authorization: Bearer <api key>"
```

**requests**

```python
import requests

response = requests.delete(
    "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/tag/<tag name>",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
```

**httpx**

```python
import httpx

response = httpx.delete(
    "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/tag/<tag name>",
    headers={"Authorization": "Bearer <api key>"},
)
response.raise_for_status()
```

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.delete(
            "https://api.gov.nominal.io/api/scout/v1/versioning/<resource rid>/tag/<tag name>",
            headers={"Authorization": "Bearer <api key>"},
        ) as response:
            response.raise_for_status()

asyncio.run(main())
```

Response: `204`

No content.

### Batch get tags

POST `/scout/v1/versioning/tag/batch-get`

Omits tags that are not authorized.

Body

The body is an array of [`ResourceAndCommitId`](https://dev.nominal.io/api/rest/versioning-service.md#resourceandcommitid).

Fields of `ResourceAndCommitId`

`resourceRid` string (RID) required
:   ​

`commitId` string required
:   ​

Response

The body is an array of [`Tag`](https://dev.nominal.io/api/rest/versioning-service.md#tag).

Fields of `Tag`

`rid` string (RID)
:   ​

`name` string
:   ​

`resourceRid` string (RID)
:   ​

`commit` string
:   ​

`createdBy` string (RID)
:   ​

`createdAt` string (date-time)
:   ​

Request

**curl**

```shell
curl -X POST "https://api.gov.nominal.io/api/scout/v1/versioning/tag/batch-get" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '[
  {
    "resourceRid": "<resource rid>",
    "commitId": "<commit id>"
  }
]'
```

**requests**

```python
import requests

response = requests.post(
    "https://api.gov.nominal.io/api/scout/v1/versioning/tag/batch-get",
    headers={"Authorization": "Bearer <api key>"},
    json=[{"resourceRid": "<resource rid>", "commitId": "<commit id>"}],
)
response.raise_for_status()
print(response.json())
```

**httpx**

```python
import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/scout/v1/versioning/tag/batch-get",
    headers={"Authorization": "Bearer <api key>"},
    json=[{"resourceRid": "<resource rid>", "commitId": "<commit id>"}],
)
response.raise_for_status()
print(response.json())
```

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/scout/v1/versioning/tag/batch-get",
            headers={"Authorization": "Bearer <api key>"},
            json=[{"resourceRid": "<resource rid>", "commitId": "<commit id>"}],
        ) as response:
            response.raise_for_status()
            print(await response.json())

asyncio.run(main())
```

Response: `200`

```json
[
  {
    "rid": "<tag rid>",
    "name": "<tag name>",
    "resourceRid": "<resource rid>",
    "commit": "<commit id>",
    "createdBy": "<user rid>",
    "createdAt": "2026-01-01T00:00:00Z"
  }
]
```

### Delete branches

POST `/scout/v1/versioning/branch/batch-delete`

Deletes the branch pointers. Throws if any resource or branch is non-existent or unauthorized. Throws if any attempt is made to delete “main”.

Body

The body is an array of [`ResourceAndBranchName`](https://dev.nominal.io/api/rest/versioning-service.md#resourceandbranchname).

Fields of `ResourceAndBranchName`

`resourceRid` string (RID) required
:   ​

`branchName` string required
:   ​

Response

No content (HTTP 204).

Request

**curl**

```shell
curl -X POST "https://api.gov.nominal.io/api/scout/v1/versioning/branch/batch-delete" \
  -H "Authorization: Bearer <api key>" \
  -H "Content-Type: application/json" \
  --data '[
  {
    "resourceRid": "<resource rid>",
    "branchName": "<branch name>"
  }
]'
```

**requests**

```python
import requests

response = requests.post(
    "https://api.gov.nominal.io/api/scout/v1/versioning/branch/batch-delete",
    headers={"Authorization": "Bearer <api key>"},
    json=[{"resourceRid": "<resource rid>", "branchName": "<branch name>"}],
)
response.raise_for_status()
```

**httpx**

```python
import httpx

response = httpx.post(
    "https://api.gov.nominal.io/api/scout/v1/versioning/branch/batch-delete",
    headers={"Authorization": "Bearer <api key>"},
    json=[{"resourceRid": "<resource rid>", "branchName": "<branch name>"}],
)
response.raise_for_status()
```

**aiohttp**

```python
import asyncio

import aiohttp

async def main() -> None:
    async with aiohttp.ClientSession() as session:
        async with session.post(
            "https://api.gov.nominal.io/api/scout/v1/versioning/branch/batch-delete",
            headers={"Authorization": "Bearer <api key>"},
            json=[{"resourceRid": "<resource rid>", "branchName": "<branch name>"}],
        ) as response:
            response.raise_for_status()

asyncio.run(main())
```

Response: `204`

No content.

## Errors

[Errors](https://dev.nominal.io/api/legacy.md#errors) shows how these errors are sent.

Each error’s `errorName` is `Scout:` followed by its name below.

| Status | Name | Notes |
| --- | --- | --- |
| 400 | `DeleteMainBranch` |  |
| 400 | `HistoryPageSizeTooLarge` |  |
| 404 | `BranchNotFound` |  |
| 404 | `CommitNotFound` |  |
| 404 | `CommitsNotFound` |  |
| 404 | `ResourceNotFound` |  |
| 404 | `ResourcesNotFound` |  |
| 404 | `TagNotFound` |  |
| 409 | `CommitConflict` |  |
| 409 | `CommitIdExists` |  |
| 409 | `CommitPointerNameConflict` |  |
| 409 | `ResourceAlreadyVersioned` |  |

## Types

### Branch

`rid` string (RID) required
:   ​

`name` string required
:   ​

`resourceRid` string (RID) required
:   ​

`commit` string required
:   ​

`createdBy` string (RID) required
:   ​

`createdAt` string (date-time) required
:   ​

`updatedAt` string (date-time) required
:   ​

### Commit

`id` string required
:   ​

`resourceRid` string (RID) required
:   ​

`parentCommit` string
:   ​

`mergeParentCommit` string
:   ​

`message` string required
:   ​

`isWorkingState` boolean required
:   A working state commit is created via the `saveWorkingState` endpoint and is non-permanent. In the future, it may be compacted and not exist.

`committedBy` string (RID) required
:   ​

`committedAt` string (date-time) required
:   ​

### ResourceAndBranchName

`resourceRid` string (RID) required
:   ​

`branchName` string required
:   ​

### ResourceAndCommitId

`resourceRid` string (RID) required
:   ​

`commitId` string required
:   ​

### Tag

`rid` string (RID) required
:   ​

`name` string required
:   ​

`resourceRid` string (RID) required
:   ​

`commit` string required
:   ​

`createdBy` string (RID) required
:   ​

`createdAt` string (date-time) required
:   ​

Page design based on [Scalar](https://scalar.com), MIT License.