Enterprise API Reference

Complete reference for all enterprise endpoints. All enterprise endpoints require JWT authentication and appropriate RBAC permissions.

Enterprise endpoints are scoped to organizations via the URL path: /v1/organizations/:orgId/...

Organizations

POST /v1/organizations

Create a new organization.

curl -X POST https://api.hippocortex.dev/v1/organizations \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Corp", "slug": "acme-corp"}'

Required Permission: Authenticated user (becomes owner)

GET /v1/organizations

List organizations the user belongs to.

curl https://api.hippocortex.dev/v1/organizations \
  -H "Authorization: Bearer <jwt>"

GET /v1/organizations/:orgId

Get organization details.

curl https://api.hippocortex.dev/v1/organizations/org-123 \
  -H "Authorization: Bearer <jwt>"

Required Permission: org:read

PATCH /v1/organizations/:orgId

Update organization settings.

curl -X PATCH https://api.hippocortex.dev/v1/organizations/org-123 \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Corporation"}'

Required Permission: org:update

Teams

POST /v1/organizations/:orgId/teams

Create a team.

curl -X POST https://api.hippocortex.dev/v1/organizations/org-123/teams \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Engineering", "description": "Product engineering team"}'

Required Permission: team:create

GET /v1/organizations/:orgId/teams

List teams in the organization.

curl https://api.hippocortex.dev/v1/organizations/org-123/teams \
  -H "Authorization: Bearer <jwt>"

Required Permission: team:list

GET /v1/organizations/:orgId/teams/:teamId

Get team details including members.

curl https://api.hippocortex.dev/v1/organizations/org-123/teams/team-456 \
  -H "Authorization: Bearer <jwt>"

PATCH /v1/organizations/:orgId/teams/:teamId

Update team settings.

Required Permission: team:update

DELETE /v1/organizations/:orgId/teams/:teamId

Delete a team.

Required Permission: team:delete

Members

POST /v1/organizations/:orgId/members/invite

Invite a member to the organization.

curl -X POST https://api.hippocortex.dev/v1/organizations/org-123/members/invite \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "alice@example.com",
    "role": "developer",
    "teamIds": ["team-456"]
  }'

Required Permission: member:invite

Request Body:

Field	Type	Required	Description
`email`	string	Yes	Invitee email
`role`	string	Yes	Org role: owner, admin, manager, developer, analyst, viewer
`teamIds`	string[]	No	Teams to add the member to

GET /v1/organizations/:orgId/members

List organization members.

curl https://api.hippocortex.dev/v1/organizations/org-123/members \
  -H "Authorization: Bearer <jwt>"

Required Permission: member:list

PATCH /v1/organizations/:orgId/members/:memberId

Update member role.

Required Permission: member:update_role

DELETE /v1/organizations/:orgId/members/:memberId

Remove a member.

Required Permission: member:remove

Agent Identities

POST /v1/organizations/:orgId/agents

Create an agent identity.

curl -X POST https://api.hippocortex.dev/v1/organizations/org-123/agents \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "deploy-bot",
    "description": "Automated deployment agent",
    "framework": "openai",
    "teamId": "team-456",
    "metadata": {"version": "2.0"}
  }'

Required Permission: agent:create

GET /v1/organizations/:orgId/agents

List agent identities.

Required Permission: agent:read

PATCH /v1/organizations/:orgId/agents/:agentId

Update agent identity.

Required Permission: agent:update

DELETE /v1/organizations/:orgId/agents/:agentId

Delete agent identity.

Required Permission: agent:delete

Memory Namespaces

POST /v1/organizations/:orgId/namespaces

Create a memory namespace.

curl -X POST https://api.hippocortex.dev/v1/organizations/org-123/namespaces \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "engineering-data",
    "description": "Engineering team memories",
    "sensitivity": "internal",
    "teamIds": ["team-456"]
  }'

Required Permission: namespace:create

Sensitivity Levels: public | internal | confidential | restricted

GET /v1/organizations/:orgId/namespaces

List namespaces.

Required Permission: namespace:read

PATCH /v1/organizations/:orgId/namespaces/:namespaceId

Update namespace settings.

Required Permission: namespace:update

Policies

POST /v1/organizations/:orgId/policies

Create an access policy.

curl -X POST https://api.hippocortex.dev/v1/organizations/org-123/policies \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Engineering read access",
    "effect": "allow",
    "resource": "namespace:ns-engineering",
    "action": "read",
    "conditions": {"team": "team-456"},
    "priority": 100
  }'

Required Permission: policy:create

Request Body:

Field	Type	Required	Description
`name`	string	Yes	Policy name
`effect`	string	Yes	`allow` or `deny`
`resource`	string	Yes	Resource pattern (e.g., `namespace:*`)
`action`	string	Yes	Action (e.g., `read`, `write`, `*`)
`conditions`	object	No	Conditions for policy activation
`priority`	number	Yes	Evaluation priority (higher = first)

GET /v1/organizations/:orgId/policies

List policies.

Required Permission: policy:read

PATCH /v1/organizations/:orgId/policies/:policyId

Update a policy.

Required Permission: policy:update

DELETE /v1/organizations/:orgId/policies/:policyId

Delete a policy.

Required Permission: policy:update

Audit Logs

GET /v1/organizations/:orgId/audit

Query audit logs.

curl "https://api.hippocortex.dev/v1/organizations/org-123/audit?action=reveal&limit=50" \
  -H "Authorization: Bearer <jwt>"

Required Permission: audit:read

Query Parameters:

Parameter	Type	Description
`action`	string	Filter by action type
`actorId`	string	Filter by actor
`resourceType`	string	Filter by resource type
`startDate`	string	Start of time range (ISO 8601)
`endDate`	string	End of time range (ISO 8601)
`limit`	number	Results per page (max 100)
`cursor`	string	Pagination cursor

GET /v1/organizations/:orgId/access-logs

Query memory access logs.

curl "https://api.hippocortex.dev/v1/organizations/org-123/access-logs?limit=50" \
  -H "Authorization: Bearer <jwt>"

Required Permission: audit:read

Lineage

GET /v1/organizations/:orgId/lineage/:memoryId

Get lineage for a specific memory.

curl https://api.hippocortex.dev/v1/organizations/org-123/lineage/mem-789 \
  -H "Authorization: Bearer <jwt>"

Required Permission: lineage:read

Response:

{
  "ok": true,
  "data": {
    "memoryId": "mem-789",
    "sourceEvents": ["evt-001", "evt-002", "evt-003"],
    "derivedArtifacts": ["art-001"],
    "lineage": [
      {
        "from": "evt-001",
        "to": "mem-789",
        "type": "captured_from",
        "timestamp": "2025-01-15T10:00:00Z"
      }
    ]
  }
}

GET /v1/organizations/:orgId/lineage/graph/:memoryId

Get the full lineage graph for a memory.

curl https://api.hippocortex.dev/v1/organizations/org-123/lineage/graph/mem-789 \
  -H "Authorization: Bearer <jwt>"

Returns the complete directed graph showing how knowledge was derived from source events through intermediate memories to compiled artifacts.

Lifecycle Policies

POST /v1/organizations/:orgId/lifecycle-policies

Create a lifecycle policy.

curl -X POST https://api.hippocortex.dev/v1/organizations/org-123/lifecycle-policies \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Standard retention",
    "retentionDays": 90,
    "archiveAfterDays": 180,
    "deleteAfterDays": 365,
    "scope": "namespace:ns-engineering"
  }'

Required Permission: lifecycle:manage

GET /v1/organizations/:orgId/lifecycle-policies

List lifecycle policies.

curl https://api.hippocortex.dev/v1/organizations/org-123/lifecycle-policies \
  -H "Authorization: Bearer <jwt>"

PATCH /v1/organizations/:orgId/lifecycle-policies/:policyId

Update a lifecycle policy.

Required Permission: lifecycle:manage

DELETE /v1/organizations/:orgId/lifecycle-policies/:policyId

Delete a lifecycle policy.

Required Permission: lifecycle:manage

Authentication Requirements Summary

Endpoint Group	Auth Type	Required Role (Minimum)
Organizations	JWT	Authenticated (create), `org:read` (view)
Teams	JWT	`team:create` / `team:list`
Members	JWT	`member:invite` / `member:list`
Agents	JWT	`agent:create` / `agent:read`
Namespaces	JWT	`namespace:create` / `namespace:read`
Policies	JWT	`policy:create` / `policy:read`
Audit	JWT	`audit:read`
Lineage	JWT	`lineage:read`
Lifecycle	JWT	`lifecycle:manage`