Predicates

Endpoints

Method	Path	Description
GET	`/v1/predicates`	List predicates with aliases
POST	`/v1/predicates`	Register a new predicate
GET	`/v1/predicates/{id}`	Get predicate by ID
POST	`/v1/predicates/{id}/aliases`	Propose an alias
PATCH	`/v1/predicates/{id}/aliases/{alias_id}`	Activate or deprecate an alias

The predicate registry is a controlled vocabulary for relationship and assertion types. Predicates like works_at, located_in, and has_title define the schema for the knowledge graph. Aliases allow multiple surface forms (e.g., employed_by mapping to works_at) to be normalized to canonical predicates.

List Predicates

GET /v1/predicates List all registered predicates, optionally including their alias mappings.

integer

default:"50"

Maximum results to return.

string

Pagination cursor from a previous response.

boolean

default:"true"

Include alias mappings in the response.

curl "http://localhost:3000/v1/predicates?limit=10&include_aliases=true" \
  -H "Authorization: Bearer $TOKEN"

{
  "results": [
    {
      "predicate_id": "works_at",
      "description": "Subject works for or is employed by object",
      "status": "active",
      "usage_count": 42,
      "aliases": [
        {
          "id": "predicate_alias:aaa...",
          "alias": "employed_by",
          "alias_type": "raw_string",
          "confidence": 0.95,
          "status": "active"
        }
      ]
    }
  ],
  "cursor": null,
  "has_more": false,
  "total": 1
}

Register Predicate

POST /v1/predicates Register a new predicate in the controlled vocabulary. Returns 201 Created on success.

string

required

Unique predicate identifier (e.g., works_at, located_in). Use snake_case.

string

Human-readable description of the predicate’s semantics.

curl -X POST http://localhost:3000/v1/predicates \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "predicate_id": "works_at",
    "description": "Subject works for or is employed by object"
  }'

{
  "id": "predicate_registry:550e8400-...",
  "predicate_id": "works_at",
  "description": "Subject works for or is employed by object",
  "status": "active",
  "usage_count": 0,
  "created_at": "2026-02-01T12:00:00Z"
}

Get Predicate

GET /v1/predicates/{id} Retrieve a single predicate by its record ID, including all alias mappings.

string

required

Predicate registry record ID (e.g., predicate_registry:550e8400-...).

curl http://localhost:3000/v1/predicates/predicate_registry:550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer $TOKEN"

{
  "predicate_id": "works_at",
  "description": "Subject works for or is employed by object",
  "status": "active",
  "semantics": {
    "cardinality": "many",
    "conflict_policy": "supersede_by_recency"
  },
  "aliases": [
    {
      "id": "predicate_alias:aaa...",
      "alias": "employed_by",
      "confidence": 0.95,
      "status": "active"
    }
  ]
}

Propose Alias

POST /v1/predicates/{id}/aliases Propose a new alias mapping for a predicate. Aliases start with status proposed and must be activated separately. Returns 201 Created on success.

string

required

Predicate registry record ID.

string

required

The alias string (e.g., employed_by).

string

default:"raw_string"

Type of alias. One of: raw_string, plugin_code, schema_field.

number

default:"0.9"

Confidence score for the alias mapping (0.0 to 1.0).

string

default:"global"

Scope of the alias. One of: global, plugin_only, source_type.

string

Source plugin identifier if the alias was generated by a plugin.

curl -X POST http://localhost:3000/v1/predicates/predicate_registry:550e8400-.../aliases \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "alias": "employed_by",
    "alias_type": "raw_string",
    "confidence": 0.95
  }'

{
  "id": "predicate_alias:bbb...",
  "alias": "employed_by",
  "alias_type": "raw_string",
  "predicate_id": "works_at",
  "confidence": 0.95,
  "status": "proposed"
}

Update Alias Status

PATCH /v1/predicates/{id}/aliases/{alias_id} Activate or deprecate a predicate alias.

string

required

Predicate registry record ID.

string

required

Predicate alias record ID (e.g., predicate_alias:bbb...).

string

required

New alias status. One of: proposed, active, deprecated.

curl -X PATCH http://localhost:3000/v1/predicates/predicate_registry:550e8400-.../aliases/predicate_alias:bbb... \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"status": "active"}'

{
  "id": "predicate_alias:bbb...",
  "alias": "employed_by",
  "status": "active",
  "confidence": 0.95
}

HTTP API

MCP

Command line

Endpoints

List Predicates

Register Predicate

Get Predicate

Propose Alias

Update Alias Status

​Endpoints

​List Predicates

​Register Predicate

​Get Predicate

​Propose Alias

​Update Alias Status

Endpoints

List Predicates

Register Predicate

Get Predicate

Propose Alias

Update Alias Status