Skip to content
shiftagent Integration API

Retrieve a role.

GET
/roles/{role_id}
 
curl --request GET \
  --url https://shiftagent.example.com/roles/example \
  --header 'Authorization: Bearer <token>'

Fetch a role by ID.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

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

Internal role ID.

Responses

Section titled “ Responses ”

200

Section titled “200 ”

The role.

Media type application/json

Tenant-scoped access profile: optional repository override + skill narrowing. Effective repository = repository_id ?? tenant default; effective skills = effective repository’s skills ∩ skill_access.

object
object
required
string
Allowed value: role
id
required
string
/^rol_[A-Za-z0-9]+$/
tenant_id
required
string
/^tnt_[A-Za-z0-9]+$/
name
required

Unique per tenant — load-bearing for replay-safe provisioning (deterministic 409 + conflicting_resource_id recovery).

string
<= 255 characters
description
required

Human-readable purpose.

string | null
repository_id
required

Repository override; null falls through to the tenant default repository.

string | null
/^rep_[A-Za-z0-9]+$/
skill_access
required
One of: discriminator: mode

Grant every skill of the role’s effective repository.

object
mode
required

Access-mode discriminator.

string
Allowed value: all
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": "role",
  "skill_access": {
    "mode": "all"
  }
}

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