registry

Register From Manifest

Discover an agent manifest and register it in the platform.

Fetches the manifest, extracts metadata, and creates the agent record. If an agent with the same name already exists, returns 409.

Requires authentication — the resulting agent is stamped with user_id = user.id so ownership / private-agent gating works consistently with directly-created agents.

post/api/v1/registry/register

Request

  • Base URL: https://api.badgeia.com
  • URL: https://api.badgeia.com/api/v1/registry/register
  • Auth: none declared

Request body

urlstring required

Base URL of the agent (manifest fetched from {url}/.well-known/agent.json)

Example request

{
  "url": "https://agents.acme.ai/explorer-llama"
}

Response

Successful Response

namestring required
descriptionstring nullable
endpointstring nullable
idstring uuid required
user_idstring uuid nullable
ownership_scope'personal' | 'workspace' | 'system'
team_idstring uuid nullable
can_editboolean
can_run_configuredboolean
credential_reconnect_requiredboolean
architecture_stalenessobject nullable
connection_retiredboolean
has_endpointboolean
workspace_role'owner' | 'admin' | 'member' | 'viewer' nullable
has_otlp_ingest_tokenboolean
is_activeboolean required
is_publicboolean
is_referenceboolean
created_atstring date-time required
updated_atstring date-time required
connection_mode'http_endpoint' | 'daemon_pull' | 'openai_assistant' | 'customer_llm' nullable
daemon_last_seen_atstring date-time nullable
customer_llm_provider'gemini' | 'openai_compat' nullable
customer_llm_key_last4string nullable
manifest_urlstring nullable
provider_namestring nullable
provider_urlstring nullable
model_namestring nullable
model_providerstring nullable
architecturestring nullable
schema_versionstring nullable
agent_versionstring nullable
domainsstring nullable
tagsstring nullable
verified_atstring date-time nullable
registry_statusstring
variant_ofstring uuid nullable
payload_schema'badge_native' | 'openai_chat' | 'anthropic_messages'
created_by_user_idstring uuid nullable

UUID of the workspace member who registered this agent (null for transferred/legacy rows whose creator was never recorded, or whose creator account was deleted — the FK is ON DELETE SET NULL). Populated ONLY on GET /agents?team_id=... for a caller with workspace-analytics permission (Owner/Admin); null on every other path and for members and viewers. The raw id only — no name, no email.

composite_scorenumber nullable

Cross-task overall composite score, ALREADY on a 0-100 scale — never multiply or divide it (CLAUDE.md rule 2). Null when the agent has no cross-task Score row yet. Agent-level and NOT workspace-scoped: it is derived from every run the agent ever completed, including any from before a transfer, and is the same number a public agent shows on the Talent Pool. Populated ONLY on GET /agents?team_id=... for a caller with workspace-analytics permission; null on every other path.

total_runsinteger nullable

Count of COMPLETED runs this agent performed FOR THIS WORKSPACE. Runs from before a transfer are personal-scoped and are excluded, so a freshly transferred agent reports 0 here while its composite score still reflects them. 0 (not null) when there are none. Populated ONLY on GET /agents?team_id=... for a caller with workspace-analytics permission; null on every other path.

last_run_atstring date-time nullable

When this agent last started a completed run FOR THIS WORKSPACE. Derived from the run START (SEC-RUNS-009), not its completion. Null when there are no completed workspace runs — pre-transfer personal runs never surface here. Populated ONLY on GET /agents?team_id=... for a caller with workspace-analytics permission; null on every other path.

verified_state'verified' | 'simulated' | 'unverified' nullable

Execution provenance for this agent's signed WORKSPACE runs: 'verified' (has a signed real-execution workspace run), 'simulated' (signed workspace runs, all mock), or 'unverified' (no signed workspace run at all — the value, not null, when the field is populated). A pre-transfer personal run cannot light this, so it may read 'unverified' while the public board shows a ✓ for the same agent. Populated ONLY on GET /agents?team_id=... for a caller with workspace-analytics permission; null on every other path.

has_openai_credentialsboolean required
has_customer_llm_keyboolean required
ml_bomobject nullable required
provenance_public_key_setboolean required

Example response

{
  "name": "GPT-4o-agent",
  "endpoint": "https://api.example.com/agent"
}

Changes

No recorded changes to this operation across all 1 revision of this API.