---
title: "List the versions of a specification"
method: GET
path: "/api/projects/{projectId}/specs/{specId}/versions"
tags: ["API Specs"]
---

# List the versions of a specification

`GET /api/projects/{projectId}/specs/{specId}/versions`

## Request

- Base URL: `https://api.routebase.dev`
- URL: `https://api.routebase.dev/api/projects/{projectId}/specs/{specId}/versions`
- Auth: API key in header `X-API-Key`

Returns the versions of a specification with their status and publish target.
Only a version whose status is `published` is frozen, so anything else can still
change underneath you.

## Path parameters

- `ProjectId` string, uuid, required
- `SpecId` string, uuid, required

## Query parameters

- `Skip` integer
- `Take` integer

## Headers

- `X-RB-Region` string

## Response `200`

A page of versions.

- SpecVersionList: A page of specification versions.
  - `items` SpecVersion[], required: The versions on this page.
    - `id` string, uuid, required: Public id of the version.
    - `versionNumber` string, required: The version label, for example 1.2.0. It follows the numbering scheme of the organization.
    - `status` 'draft' | 'review' | 'published' | 'deprecated', required: The lifecycle state of a specification version. Only `published` is frozen and therefore safe to generate clients from.
    - `createdAt` string, date-time, required: When the version was created, in UTC.
    - `publishedAt` string, date-time, nullable: When the version was published, in UTC. Null while it is still a draft or in review.
    - `publishTarget` 'internal' | 'public' | 'exportOnly': Who a published version is visible to.
    - `rowVersion` string, nullable: Base64 concurrency token.
  - `totalCount` integer, required: Total number of versions of this specification, ignoring paging.

## Other responses

- `401`: The API key is missing, invalid, expired or revoked. A US organization calling without `X-RB-Region: us` also lands here, because the request reached the wrong region.
- `403`: The key is valid but lacks the permission or the project scope for this call. A scoped key is also refused on organization level operations by design.
- `404`: The resource does not exist, or it belongs to another organization or project. Both cases answer the same way on purpose, so the API cannot be used to probe for foreign identifiers.
- `429`: The rate limit was exceeded. The `Retry-After` header gives the seconds to wait.

---

[API](https://skmtc.dev/routebase/apis/routebase-public-api.md) · [All operations](https://skmtc.dev/routebase/apis/routebase-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/routebase/apis/routebase-public-api/revisions/7187df489f27?raw)