Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.phinite.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Hosted A2A URLs

External callers reach registered agents through the API gateway AI-core lane. The frontend builds URLs with the same rules as buildA2aUrl in the product:
Deployment statusURL patternExample shape
Live{gateway}/api/v1/ai/a2a/{flowId}Production routing; registry ID omitted
Test{gateway}/api/v1/ai/a2a/{flowId}/{registryId}Validation build tied to a specific registry row
# Live
https://app-dev.phinite.ai/api/v1/ai/a2a/{flowId}

# Test
https://app-dev.phinite.ai/api/v1/ai/a2a/{flowId}/{a2aregistryid}
Replace the host with your environment’s gateway base (NEXT_PUBLIC_BACKEND_SERVER_URL → /api/v1, then append /ai for the AI-core lane). Graph Studio and Agent Registry copy the authoritative string for your tenant—always use the value shown in the UI rather than constructing URLs manually. For local development with the dev API proxy, the same paths may appear under http://localhost:3000/api/v1/ai/a2a/....

​
Registry lifecycle

Each expose action creates an A2A registry row with deployment status test by default.
StatusMeaningHosted URL
testInternal validation before broad discoveryIncludes {registryId} in path
liveProduction build for the agent graphShort path with {flowId} only
One live build per agent graph per workspace. Promoting a build to live demotes any previous live row for the same flowid back to test.

​
Promote to live

From Agent Cards, select a test build and use Push To Prod (promote flow). The app calls: 
PUT /api/v1/a2a-registry/{a2aregistryid}/promote-live
No request body is required. The response is the updated registry document with status: "live".

​
Visibility and authentication

Each Agent Card declares visibility:
VisibilityUI labelInvoke behaviour (high level)
publicPublicCallable by any client presenting a valid Phinite API key
organizationOrganisationCallable only when the API key belongs to the same organisation as the registry row
At runtime, the gateway A2ARegistryAccess middleware validates visibility when agents are invoked (for example POST /api/v1/ai/a2a/agents/{registryId}). Organisation-scoped agents return an auth error if the caller’s org does not match. Auth scheme in the product: callers use your organisation’s API key (JWT) in the X-API-Key header unless your deployment configures additional schemes.

​
Agent Card contract for integrators

Integrators and A2A-compatible clients should consume:
  • Agent name and description from the Agent Card
  • Skills — each skill lists supported input modes and output modes (MIME types)
  • Discoverability tags — for search and Discovery matching
  • Hosted URL — test vs live pattern above
See the Agent Registry glossary for supported MIME types. Official protocol details: A2A protocol specification.

​
Registry management API

All routes require gateway authentication (session cookie or Bearer token / API key). Base path: /api/v1/a2a-registry.
MethodPathPurpose
GET/a2a-registryList registry rows (workspaceid required; optional orgid, status, visibility, flowid, filters)
GET/a2a-registry/{a2aregistryid}Get one row (?flow=true includes decrypted flow payload)
POST/a2a-registry?workspaceid=...Create registration (Expose wizard)
PUT/a2a-registry/{a2aregistryid}Update registration
PUT/a2a-registry/{a2aregistryid}/promote-livePromote to live
DELETE/a2a-registry/{a2aregistryid}Delete registration
Permissions (api-server): assistants.flows:read|create|update|delete depending on operation.

​
Useful list query parameters

ParameterValuesUse
workspaceidstringRequired — scopes to workspace
orgidstringOrganisation filter (must match caller’s org)
statustest, liveDeployment filter
visibilitypublic, organizationTop-level visibility filter
flowidstringAll builds for one agent graph
flow_list=truebooleanReturns distinct flows only (Agent Cards dropdown)
paginationtrue / falsePaginated vs full list

Expose an agent

Create a test build and Agent Card.

Agent Cards

Promote test builds to live.