Reference

Platform API Reference

Complete Platform API documentation for the Hikigai Agent Registry.

Base URL: https://api.hikigai.com/v1

Authentication

All API requests require a Bearer token in the Authorization header:

Authorization: Bearer hk_live_your_api_key

Getting your API key: Create an API key in your Dashboard → Settings → API Keys

Token Tiers & Scopes

API keys can be restricted to specific scopes. If no scopes are provided, the key defaults to the permissions of the creator's role.

Scope	Description
`agents:invoke`	Call agents to process messages
`agents:deploy`	Create and deploy new agents
`projects:read`	View project details and members
`members:invite`	Add new collaborators to a project
`connectors:manage`	Register and configure MCP servers

Projects & Members

GET/projects

List all projects you have access to.

Response

{
  "projects": [
    {
      "id": "proj_abc123",
      "name": "Clinical Assistant",
      "role": "OWNER",
      "member_count": 5
    }
  ]
}

POST/projects/{project_id}/members

Invite a new member to the project.

Request Body

{
  "email": "doctor@hospital.org",
  "role": "DEVELOPER"
}

Agents

POST/agents/deploy

Deploy a new agent.

Request Body

{
  "name": "sentiment-analyzer",
  "instruction": "Analyze sentiment of text. Return positive, negative, or neutral.",
  "model": "claude-3-sonnet",
  "description": "Analyzes text sentiment",
  "category": "NLP",
  "tags": ["sentiment", "text"],
  "timeout": 30,
  "public": false
}

Response

{
  "agent_id": "ag_abc123def456",
  "name": "sentiment-analyzer",
  "slug": "sentiment-analyzer",
  "status": "deployed",
  "endpoint": "https://api.hikigai.com/v1/agents/ag_abc123def456/invoke"
}

GET/agents

List all your agents with pagination.

Query Parameters

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`per_page`	integer	Items per page (default: 20, max: 100)
`category`	string	Filter by category
`search`	string	Search by name

Response

{
  "agents": [
    {
      "id": "ag_abc123def456",
      "name": "sentiment-analyzer",
      "slug": "sentiment-analyzer",
      "description": "Analyzes sentiment",
      "category": "NLP",
      "status": "active",
      "invocation_count": 1542
    }
  ],
  "total": 5,
  "page": 1,
  "per_page": 20
}

GET/agents/{agent_id}

Get details of a specific agent.

Response

{
  "id": "ag_abc123def456",
  "name": "sentiment-analyzer",
  "slug": "sentiment-analyzer",
  "model": "claude-3-sonnet",
  "instruction": "Analyze sentiment...",
  "description": "Analyzes text sentiment",
  "category": "NLP",
  "tags": ["sentiment", "text"],
  "status": "active",
  "endpoint": "https://api.hikigai.com/v1/agents/ag_abc123def456/invoke",
  "invocation_count": 1542
}

DELETE/agents/{agent_id}

Delete an agent.

Response

{
  "message": "Agent deleted successfully"
}

Data Connectors (MCP)

GET/connectors/registry

List all available public connectors.

Response

{
  "connectors": [
    {
      "slug": "epic-fhir",
      "name": "Epic FHIR",
      "category": "EHR",
      "status": "Verified"
    }
  ]
}

POST/projects/{project_id}/connectors

Request Body

{
  "name": "Internal DB",
  "mcp_url": "https://mcp.internal.org/",
  "category": "Data"
}

Invocation

POST/agents/{agent_id}/invoke

Invoke an agent with a message.

Request Body

{
  "message": "I love this product! It works great.",
  "session_id": "user-123",
  "stream": false,
  "timeout": 300
}

Response

{
  "content": "The sentiment is positive with high confidence.",
  "agent_id": "ag_abc123def456",
  "session_id": "user-123",
  "latency_ms": 245,
  "tokens_used": 127,
  "tools_called": [],
  "request_id": "req_xyz789",
  "trace_id": "trace_abc123"
}

timeout (optional, 5–300 seconds) — omit to use the agent's deploy-time default. When provided, overrides that limit for this call only. Also set your HTTP client timeout (e.g. requests.post(..., timeout=300)) so your app does not give up before the server responds. Deploy behavior is unchanged; this field is opt-in at invoke time.

Streaming: Set stream: true to receive Server-Sent Events with chunked responses.

Usage & Limits

GET/usage

Get your current usage statistics.

Response

{
  "period_start": "2024-01-01T00:00:00Z",
  "period_end": "2024-01-31T23:59:59Z",
  "invocations_limit": 10000,
  "invocations_used": 4521,
  "agents_limit": 100,
  "agents_used": 5
}

GET/me

Get current developer information.

Response

{
  "id": "dev_abc123",
  "name": "John Doe",
  "email": "john@example.com",
  "company": "Acme Inc",
  "tier": "pro",
  "scopes": ["invoke", "deploy", "manage"]
}

Error Codes

The API returns standard HTTP status codes with detailed error messages:

Code	Name	Description
`400`	Bad Request	Invalid request body or parameters
`401`	Unauthorized	Invalid or missing API key
`403`	Forbidden	Insufficient permissions
`404`	Not Found	Agent not found
`429`	Too Many Requests	Rate limit exceeded
`500`	Server Error	Internal server error

Error Response Format

{
  "error": "rate_limit_exceeded",
  "message": "You have exceeded your rate limit. Please retry after 60 seconds.",
  "retry_after": 60
}

Rate Limit Headers

All responses include rate limit information:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1704153600
Retry-After: 60  # Only on 429 responses