Version: Next (latest)

Repository API Reference

The Repository API provides programmatic access to synchronizing and retrieving database definitions for any repository within your namespace. Use this API to query the latest schemas, inspect forward/rollback migrations, and fetch seed datasets.

Overview & Base URL

All API requests are served over HTTPS and prefixed with the following versioned base path:

https://api.shed.dev/repository_api/v1

:::info Relative Development Base When running against a local or self-hosted Shed daemon, endpoints are mounted at: /repository_api/v1 :::

Authentication

Every request to the Repository API requires a valid API key supplied in the X-API-Key request header:

X-API-Key: sk_live_your_api_key_here

Header	Type	Required	Description
`X-API-Key`	`string`	Yes	Your secret API key generated in the workspace settings.

:::warning Security Best Practice Never expose your API key in client-side code or public repositories. Requests with missing, malformed, or expired keys return an HTTP 401 Unauthorized response. :::

Common Path Parameters

Most endpoints in this API require identifying the organization/owner namespace and the target repository:

Parameter	Type	Required	Description	Example
`namespace`	`string`	Yes	Organization, user, or project namespace.	`acme-corp`
`repository`	`string`	Yes	Unique repository identifier.	`production-db`

1. Changelog Sync

Retrieve the full repository state in a single request. This bundle includes the latest active schema definition, all historical migration stages, and configured seed datasets.

GET /{namespace}/{repository}

Request Example

cURL
TypeScript / Node
Python

curl -X GET "https://api.shed.dev/repository_api/v1/acme-corp/production-db" \
  -H "X-API-Key: sk_live_your_api_key_here" \
  -H "Accept: application/json"

const response = await fetch(
  'https://api.shed.dev/repository_api/v1/acme-corp/production-db',
  {
    headers: {
      'X-API-Key': process.env.SHED_API_KEY!,
      'Accept': 'application/json',
    },
  }
);

const changelog = await response.json();
console.log(changelog);

import os
import requests

url = "https://api.shed.dev/repository_api/v1/acme-corp/production-db"
headers = {
    "X-API-Key": os.getenv("SHED_API_KEY"),
    "Accept": "application/json",
}

response = requests.get(url, headers=headers)
print(response.json())

Response (`200 OK`)

{
  "schema": {
    "id": "sch_01HZX87654321",
    "checksum": "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
    "sql": "CREATE TABLE users (\n  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n  email VARCHAR(255) NOT NULL UNIQUE,\n  created_at TIMESTAMPTZ DEFAULT NOW()\n);"
  },
  "migrations": [
    {
      "id": "mig_01HZX1001",
      "name": "20261001_create_users",
      "schemaId": "sch_01HZX87654321",
      "checksumUp": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
      "sqlUp": "CREATE TABLE users (id UUID PRIMARY KEY, email VARCHAR(255) NOT NULL);",
      "checksumDown": "sha256:5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8",
      "sqlDown": "DROP TABLE IF EXISTS users;"
    }
  ],
  "seeds": [
    {
      "id": "seed_01HZX2001",
      "name": "seed_default_roles",
      "schemaId": "sch_01HZX87654321",
      "checksum": "sha256:4b227777d4dd1fc61c6f884f48641d02b4d121d3fd328cb08b5531fcacdabf8a",
      "sql": "INSERT INTO roles (name) VALUES ('admin'), ('member'), ('viewer') ON CONFLICT DO NOTHING;"
    }
  ]
}

2. Get Latest Schema

Retrieve only the latest current schema definition for the repository.

GET /{namespace}/{repository}/schema

Response (`200 OK`)

{
  "id": "sch_01HZX87654321",
  "checksum": "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
  "sql": "CREATE TABLE users (\n  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),\n  email VARCHAR(255) NOT NULL UNIQUE,\n  created_at TIMESTAMPTZ DEFAULT NOW()\n);"
}

Schema Object Fields

Field	Type	Description
`id`	`string`	Unique identifier of this compiled schema version.
`checksum`	`string`	Cryptographic SHA-256 hash verifying the schema SQL integrity.
`sql`	`string`	Complete SQL DDL representing the active database state.

3. Get Migrations

Fetch the chronological list of all recorded database migrations.

GET /{namespace}/{repository}/migrations

Response (`200 OK`)

[
  {
    "id": "mig_01HZX1001",
    "name": "20261001_create_users",
    "schemaId": "sch_01HZX87654321",
    "checksumUp": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
    "sqlUp": "CREATE TABLE users (id UUID PRIMARY KEY, email VARCHAR(255) NOT NULL);",
    "checksumDown": "sha256:5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8",
    "sqlDown": "DROP TABLE IF EXISTS users;"
  },
  {
    "id": "mig_01HZX1002",
    "name": "20261005_add_user_roles",
    "schemaId": "sch_01HZX87654321",
    "checksumUp": "sha256:2c26b46b68ffc68ff99b453c1d30413413422d706483bfa0f98a5e886266e7ae",
    "sqlUp": "ALTER TABLE users ADD COLUMN role VARCHAR(50) DEFAULT 'member';",
    "checksumDown": "sha256:fc920525f3b70afa2f67bf72b29171a6b9d774f3158e2e0d8daabb4d176a394a",
    "sqlDown": "ALTER TABLE users DROP COLUMN IF EXISTS role;"
  }
]

Migration Object Fields

Field	Type	Description
`id`	`string`	Unique migration ID.
`name`	`string`	Human-readable identifier (e.g. timestamp or step slug).
`schemaId`	`string`	Associated schema revision ID.
`checksumUp`	`string`	SHA-256 integrity hash of the forward (`sqlUp`) script.
`sqlUp`	`string`	SQL statement applied during forward migration.
`checksumDown`	`string`	SHA-256 integrity hash of the rollback (`sqlDown`) script.
`sqlDown`	`string`	SQL statement executed when rolling back.

4. Get Migration by ID

Retrieve detailed information for a single migration by its ID.

GET /{namespace}/{repository}/migrations/{migrationId}

Path Parameters

Parameter	Type	Required	Description	Example
`migrationId`	`string`	Yes	Target migration ID.	`mig_01HZX1001`

Response (`200 OK`)

{
  "id": "mig_01HZX1001",
  "name": "20261001_create_users",
  "schemaId": "sch_01HZX87654321",
  "checksumUp": "sha256:9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
  "sqlUp": "CREATE TABLE users (id UUID PRIMARY KEY, email VARCHAR(255) NOT NULL);",
  "checksumDown": "sha256:5e884898da28047151d0e56f8dc6292773603d0d6aabbdd62a11ef721d1542d8",
  "sqlDown": "DROP TABLE IF EXISTS users;"
}

5. Get Seeds

List all seed scripts configured for this repository.

GET /{namespace}/{repository}/seeds

Response (`200 OK`)

[
  {
    "id": "seed_01HZX2001",
    "name": "default-roles",
    "schemaId": "sch_01HZX87654321",
    "checksum": "sha256:4b227777d4dd1fc61c6f884f48641d02b4d121d3fd328cb08b5531fcacdabf8a",
    "sql": "INSERT INTO roles (name) VALUES ('admin'), ('member'), ('viewer') ON CONFLICT DO NOTHING;"
  }
]

Seed Object Fields

Field	Type	Description
`id`	`string`	Unique seed ID.
`name`	`string`	Seed script title or purpose.
`schemaId`	`string`	Reference to the compatible schema ID.
`checksum`	`string`	SHA-256 hash verifying seed content authenticity.
`sql`	`string`	SQL commands used to populate seed data.

6. Get Seed by ID

Retrieve a specific seed definition by its identifier.

GET /{namespace}/{repository}/seeds/{seedId}

Path Parameters

Parameter	Type	Required	Description	Example
`seedId`	`string`	Yes	Target seed ID.	`seed_01HZX2001`

Response (`200 OK`)

{
  "id": "seed_01HZX2001",
  "name": "default-roles",
  "schemaId": "sch_01HZX87654321",
  "checksum": "sha256:4b227777d4dd1fc61c6f884f48641d02b4d121d3fd328cb08b5531fcacdabf8a",
  "sql": "INSERT INTO roles (name) VALUES ('admin'), ('member'), ('viewer') ON CONFLICT DO NOTHING;"
}

Status Codes & Error Handling

All failed requests return an appropriate HTTP status code accompanied by a JSON error envelope.

Error Response Schema

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The provided X-API-Key is invalid, expired, or revoked.",
    "status": 401
  }
}

HTTP Status Reference

Status Code	Meaning	Typical Cause
`200 OK`	Success	The request succeeded and returned the requested resources.
`400 Bad Request`	Invalid Parameters	Missing or malformed `{namespace}`, `{repository}`, or path IDs.
`401 Unauthorized`	Authentication Failed	Missing or invalid `X-API-Key` header.
`404 Not Found`	Resource Not Found	Target repository, migration ID, or seed ID does not exist.
`500 Server Error`	Internal Error	Unexpected server error while reading repository state.

Overview & Base URL​

Authentication​

Common Path Parameters​

1. Changelog Sync​

Request Example​

Response (200 OK)​

2. Get Latest Schema​

Response (200 OK)​

Schema Object Fields​

3. Get Migrations​

Response (200 OK)​

Migration Object Fields​

4. Get Migration by ID​

Path Parameters​

Response (200 OK)​

5. Get Seeds​

Response (200 OK)​

Seed Object Fields​

6. Get Seed by ID​

Path Parameters​

Response (200 OK)​

Status Codes & Error Handling​

Error Response Schema​

HTTP Status Reference​

Overview & Base URL

Authentication

Common Path Parameters

1. Changelog Sync

Request Example

Response (`200 OK`)

2. Get Latest Schema

Response (`200 OK`)

Schema Object Fields

3. Get Migrations

Response (`200 OK`)

Migration Object Fields

4. Get Migration by ID

Path Parameters

Response (`200 OK`)

5. Get Seeds

Response (`200 OK`)

Seed Object Fields

6. Get Seed by ID

Path Parameters

Response (`200 OK`)

Status Codes & Error Handling

Error Response Schema

HTTP Status Reference