Skip to content
shiftagent Integration API

Trigger a repository re-scan.

POST
/repositories/{repository_id}/sync
 
curl --request POST \
  --url https://shiftagent.example.com/repositories/example/sync \
  --header 'Authorization: Bearer <token>'

Starts an asynchronous fresh git read that reconciles the skill catalog with the repository contents (new skills added, removed ones pruned, versions refreshed). Responds 202 immediately with the repository showing sync.state: "syncing"; poll getRepository until ready or error. A sync already in flight responds 409.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
repository_id
required
string
/^rep_[A-Za-z0-9]+$/

Internal repository ID.

Header Parameters

Section titled “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.

Responses

Section titled “ Responses ”

202

Section titled “202 ”

Sync accepted and running.

Media type 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
id
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
Example 
{
  "object": "repository",
  "branch": "main",
  "provider": "github",
  "sync": {
    "state": "pending"
  }
}

401

Section titled “401 ”

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

Media type 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
Example 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"
}

404

Section titled “404 ”

Not found — the resource does not exist, was deprovisioned, or lies outside the integration key’s subtree (indistinguishable by design).

Media type 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
Example not_found

Unknown resource

{
  "type": "https://shiftagent.example.com/problems/not-found",
  "title": "Not found",
  "status": 404,
  "detail": "No tenant with external_id acme:tenant:999999.",
  "request_id": "req_01hzx8nf001"
}

409

Section titled “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).

Media type 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"
}