Register a repository in the integration registry.

POST

/repositories

const url = 'https://shiftagent.example.com/repositories';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"name":"field-ops","repo_url":"https://git.example.com/agent-skills/field-ops.git","branch":"main","provider":"generic","credential_id":"crd_01hzx8gitmain"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://shiftagent.example.com/repositories \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "name": "field-ops", "repo_url": "https://git.example.com/agent-skills/field-ops.git", "branch": "main", "provider": "generic", "credential_id": "crd_01hzx8gitmain" }'

Registers a git repository as a top-level, pre-authenticated registry entry (scoped to the integration root, not tenant-owned). One-time setup: register a credential (createCredential), then the repository referencing it; afterwards attach it to tenants with attachTenantRepository.

Registration kicks off an asynchronous sync that scans the repository for skills (sync.state: pending → syncing → ready, or error with sync.error set). Skills become visible via listRepositorySkills once ready.

name is unique across the registry: a duplicate responds 409 name-conflict with conflicting_resource_id — fetch that repository and continue (heals crashed setup runs).

Authorizations

integrationKey

Parameters

Header Parameters

Idempotency-Key

string

<= 255 characters

Optional idempotency key (any unique string, e.g. a UUID; max 255 chars). Responses are cached 24h per (key principal, operation, key); replays return the original status and body with Idempotency-Replayed: true. Reusing a key with a different payload responds 409 idempotency-key-conflict.

Request Body^required

application/json

Registration body for registerRepository.

object

name

required

Registry-unique name (409 name-conflict if taken).

string

<= 255 characters

repo_url

required

Git remote URL.

string format: uri

branch

Branch to scan for skills.

string

default: main

provider

Git hosting flavor.

string

default: generic

Allowed values: github gitlab bitbucket azure_devops generic

credential_id

Credential registered via createCredential. Omit for public repositories.

string

/^crd_[A-Za-z0-9]+$/

metadata

Free-form string key–value map for host/adapter bookkeeping (e.g. a host-side reference ID). Max 50 keys; values max 500 chars. Replaced wholesale when provided in updates.

object

<= 50 properties

key

additional properties

string

<= 500 characters

Examples

register_field_ops

Cold-path setup — register the skills repository

{
  "name": "field-ops",
  "repo_url": "https://git.example.com/agent-skills/field-ops.git",
  "branch": "main",
  "provider": "generic",
  "credential_id": "crd_01hzx8gitmain"
}

Responses

201

Repository registered; sync started.

application/json

Top-level, pre-authenticated registry entry for a git repository. The repository dictates which skills exist; it is attached to tenants and overridable down the resolution cascade.

object

object

required

string

Allowed value: repository

required

string

/^rep_[A-Za-z0-9]+$/

name

required

Unique across the registry.

string

<= 255 characters

repo_url

required

Git remote URL.

string format: uri

branch

required

Branch scanned for skills (tenant attachments may override).

string

default: main

provider

required

Git hosting flavor (drives auth mechanics).

string

default: generic

Allowed values: github gitlab bitbucket azure_devops generic

credential_id

required

Vault credential used to access the repository. Secret material is never readable — pre-authenticated at registration.

string | null

/^crd_[A-Za-z0-9]+$/

sync

required

Skill-discovery sync state of a repository.

object

state

required

pending — not yet scanned (or invalidated by an update); syncing — scan in flight; ready — skill catalog current; error — last scan failed (see error).

string

Allowed values: pending syncing ready error

last_synced_at

required

Completion time of the last successful scan.

string | null format: date-time

error

required

Human-readable failure reason when state is error.

string | null

skill_count

required

Number of skills currently cataloged.

integer

metadata

required

Free-form string key–value map for host/adapter bookkeeping (e.g. a host-side reference ID). Max 50 keys; values max 500 chars. Replaced wholesale when provided in updates.

object

<= 50 properties

key

additional properties

string

<= 500 characters

created_at

required

RFC 3339 / ISO 8601 timestamp, UTC.

string format: date-time

updated_at

required

RFC 3339 / ISO 8601 timestamp, UTC.

string format: date-time

Examples

registered

Newly registered repository, sync in progress

{
  "object": "repository",
  "id": "rep_01hzx8fieldops",
  "name": "field-ops",
  "repo_url": "https://git.example.com/agent-skills/field-ops.git",
  "branch": "main",
  "provider": "generic",
  "credential_id": "crd_01hzx8gitmain",
  "sync": {
    "state": "syncing",
    "last_synced_at": null,
    "error": null
  },
  "skill_count": 0,
  "metadata": {},
  "created_at": "2026-07-02T09:31:00Z",
  "updated_at": "2026-07-02T09:31:00Z"
}

401

Missing or invalid credentials — no bearer token, an unknown/revoked sk_int_ key, or an expired platform JWT.

application/problem+json

RFC 9457 problem+json error envelope. type is a URI under https://shiftagent.example.com/problems/{slug} (deployment host substituted); see the API-level problem registry for every slug.

object

type

required

Problem type URI (registry slug).

string format: uri-reference

title

required

Short, human-readable summary of the problem type.

string

status

required

HTTP status code.

integer format: int32

detail

Human-readable explanation specific to this occurrence.

string

instance

URI reference identifying this occurrence.

string format: uri-reference

request_id

Correlation ID for support and log lookup.

string

conflicting_resource_id

On name-conflict, external-id-conflict, and resource-in-use: the ID of the existing/depended-on resource — fetch it and continue (replay recovery).

string

errors

On validation-error, field-level details.

Array<object>

object

pointer

required

JSON pointer to the offending field.

string

message

required

What failed.

string

Examples

unauthorized

Missing or invalid bearer token

{
  "type": "https://shiftagent.example.com/problems/insufficient-scope",
  "title": "Unauthorized",
  "status": 401,
  "detail": "Provide a valid sk_int_ service key or platform JWT.",
  "request_id": "req_01hzx8auth001"
}

409

Conflict — name-conflict / external-id-conflict (unique name or external ID taken; conflicting_resource_id names the holder — fetch it and continue), resource-in-use (guarded delete refused), cross-tenant (referenced resource belongs to another tenant), conversation-archived (write to an archived conversation), approval-expired (approval already resolved or expired), or idempotency-key-conflict (same key, different payload).

application/problem+json

RFC 9457 problem+json error envelope. type is a URI under https://shiftagent.example.com/problems/{slug} (deployment host substituted); see the API-level problem registry for every slug.

object

type

required

Problem type URI (registry slug).

string format: uri-reference

title

required

Short, human-readable summary of the problem type.

string

status

required

HTTP status code.

integer format: int32

detail

Human-readable explanation specific to this occurrence.

string

instance

URI reference identifying this occurrence.

string format: uri-reference

request_id

Correlation ID for support and log lookup.

string

conflicting_resource_id

On name-conflict, external-id-conflict, and resource-in-use: the ID of the existing/depended-on resource — fetch it and continue (replay recovery).

string

errors

On validation-error, field-level details.

Array<object>

object

pointer

required

JSON pointer to the offending field.

string

message

required

What failed.

string

Examples

Named sub-resource already exists — recoverable

{
  "type": "https://shiftagent.example.com/problems/name-conflict",
  "title": "Name conflict",
  "status": 409,
  "detail": "A role named \"csr\" already exists in this tenant.",
  "conflicting_resource_id": "rol_01hzx8csr001",
  "request_id": "req_01hzx8conf01"
}

Guarded delete refused

{
  "type": "https://shiftagent.example.com/problems/resource-in-use",
  "title": "Resource in use",
  "status": 409,
  "detail": "Repository is attached to 1 tenant and pinned by 2 roles.",
  "conflicting_resource_id": "tnt_01hzx8acme001",
  "request_id": "req_01hzx8used01"
}

422

Unprocessable — validation-error (schema/semantic validation failed; errors[] lists JSON-pointer details) or role-required (user has multiple roles and no role_id was given).

application/problem+json

RFC 9457 problem+json error envelope. type is a URI under https://shiftagent.example.com/problems/{slug} (deployment host substituted); see the API-level problem registry for every slug.

object

type

required

Problem type URI (registry slug).

string format: uri-reference

title

required

Short, human-readable summary of the problem type.

string

status

required

HTTP status code.

integer format: int32

detail

Human-readable explanation specific to this occurrence.

string

instance

URI reference identifying this occurrence.

string format: uri-reference

request_id

Correlation ID for support and log lookup.

string

conflicting_resource_id

On name-conflict, external-id-conflict, and resource-in-use: the ID of the existing/depended-on resource — fetch it and continue (replay recovery).

string

errors

On validation-error, field-level details.

Array<object>

object

pointer

required

JSON pointer to the offending field.

string

message

required

What failed.

string

Examples

Field-level validation failure

{
  "type": "https://shiftagent.example.com/problems/validation-error",
  "title": "Validation error",
  "status": 422,
  "detail": "One or more fields failed validation.",
  "errors": [
    {
      "pointer": "/skill_access/skill_ids/0",
      "message": "skl_01hzx8unknown does not belong to the effective repository."
    }
  ],
  "request_id": "req_01hzx8val001"
}

Ambiguous role at conversation creation

{
  "type": "https://shiftagent.example.com/problems/role-required",
  "title": "Role required",
  "status": 422,
  "detail": "User usr_01hzx8jane001 holds 2 roles; pass role_id explicitly.",
  "request_id": "req_01hzx8role01"
}

Register a repository in the integration registry.

Authorizations

Parameters

Header Parameters

Request Body required

Examples

Responses

201

Examples

401

Examples

409

Examples

422

Examples

Request Body^required