Skip to content
aerandil.com
GitHub

The composition catalogue for a registry entry

GET
/v1/agent-authoring/pick-list/{registry_entry_id}
curl --request GET \
  --url https://api.aerandil.com/v1/agent-authoring/pick-list/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0 \
  --header 'Authorization: Bearer <token>'

What an author may actually build this agent out of: every object type, action, function and metric the entry is allowed to reach, intersected down twice — once against the entry’s own declared maxima (declared_action_scopes, declared_function_scopes, declared_data_classes) and once against the calling author’s clearances. A type the author cannot read is absent rather than listed-and-refused, so the pick-list never advertises a capability its holder would be denied at invocation. The entry itself is loaded under the caller’s authority, so a marking they cannot read is a 404 like any other redacted read.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
registry_entry_id
required
string format: uuid

The agent_registry_entry being authored against.

Responses

Section titled “Responses”

200

Section titled “200”

The intersected catalogue.

Media typeapplication/json
object
action_types
required
Array<object>
object
api_name
required
string
description
string
nullable
display_name
required
string
effects
required
Array
One of: discriminator: kind
object
kind
required
string
Allowed value: create
Allowed values: create
object_type
required
string
parameter_count
required
integer
target_object_type

Bound target object type for targeted actions. Untargeted actions (creates) leave it null.

string
nullable
function_types
required
Array<object>
object
api_name
required
string
description
string
nullable
display_name
required
string
parameter_count
required
integer
return_type_kind
required

Kind discriminator of the function’s declared return type (e.g. struct, money, int). The full typed schema lives in /v1/openapi.json at the per-function /invoke path.

string
target_object_type

Bound target object type for targeted functions. Unbound functions leave it null.

string
nullable
metrics
required
Array<object>

A canonical (highest-version) metric offered to the author, trimmed to what a builder needs to reference and label one.

object
description
string
nullable
grain
required

The metric’s native temporal grain.

string
Allowed values: day week month quarter year
name
required
string
version
required
integer
object_types
required
Array<object>
object
api_name
required
string
description
string
nullable
display_name
required
string
markings
required

Row-level markings applied to every instance (e.g. pii, payment_data).

Array<string>
primary_key
required

API name of the property that serves as the type’s primary key.

string
property_count
required
integer
scope_levels
required

Levels of the tenancy hierarchy at which instances of this type are allowed to live.

Array
Allowed values: tenant brand portfolio property venue
status
required

Lifecycle state of the type definition.

Allowed values: active deprecated
title_property

API name of the property used for human-readable titles (e.g. an SDK’s .toString() equivalent).

string
nullable
registry_entry_id
required
string format: uuid
Example
{
  "action_types": [
    {
      "effects": [
        {
          "kind": "create"
        }
      ]
    }
  ],
  "metrics": [
    {
      "grain": "day"
    }
  ],
  "object_types": [
    {
      "scope_levels": [
        "tenant"
      ],
      "status": "active"
    }
  ]
}

403

Section titled “403”

The bearer authenticated but does not hold the scope this operation requires.

Media typeapplication/json

Structured error wrapper. Every non-2xx response from any Aerandil endpoint serialises to this shape; the HTTP status carries the failure class (4xx/5xx), the body adds a stable code for programmatic dispatch plus a human-readable message.

object
error
required
object
code
required

Stable, programmatic error code (e.g. unauthorized, forbidden, not_found, invalid_body, invalid_url, precondition_failed, no_secondary_key). Clients dispatch on code, not on the message (which may be localised or contextualised in future versions).

string
instance_id

Request-id correlation handle echoed on the request-id response header — support teams correlate without scraping logs.

string
message
required

Human-readable explanation of the failure.

string
parameters

Per-error structured detail. The shape varies by code (e.g. forbidden_action carries {"action": "..."}; precondition_failed carries {"current_version": N}).

Examplegenerated
{
  "error": {
    "code": "example",
    "instance_id": "example",
    "message": "example",
    "parameters": "example"
  }
}

404

Section titled “404”

No such object in the caller’s tenant — which is also the answer when it exists in another tenant, by design.

Media typeapplication/json

Structured error wrapper. Every non-2xx response from any Aerandil endpoint serialises to this shape; the HTTP status carries the failure class (4xx/5xx), the body adds a stable code for programmatic dispatch plus a human-readable message.

object
error
required
object
code
required

Stable, programmatic error code (e.g. unauthorized, forbidden, not_found, invalid_body, invalid_url, precondition_failed, no_secondary_key). Clients dispatch on code, not on the message (which may be localised or contextualised in future versions).

string
instance_id

Request-id correlation handle echoed on the request-id response header — support teams correlate without scraping logs.

string
message
required

Human-readable explanation of the failure.

string
parameters

Per-error structured detail. The shape varies by code (e.g. forbidden_action carries {"action": "..."}; precondition_failed carries {"current_version": N}).

Examplegenerated
{
  "error": {
    "code": "example",
    "instance_id": "example",
    "message": "example",
    "parameters": "example"
  }
}