> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rkat.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Predicates

> Manage the predicate registry and alias mappings for relationship and assertion types.

## 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.

<ParamField query="limit" type="integer" default="50">
  Maximum results to return.
</ParamField>

<ParamField query="cursor" type="string">
  Pagination cursor from a previous response.
</ParamField>

<ParamField query="include_aliases" type="boolean" default="true">
  Include alias mappings in the response.
</ParamField>

<CodeGroup>
  ```bash Request theme={null}
  curl "http://localhost:3000/v1/predicates?limit=10&include_aliases=true" \
    -H "Authorization: Bearer $TOKEN"
  ```

  ```json Response theme={null}
  {
    "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
  }
  ```
</CodeGroup>

***

## Register Predicate

`POST /v1/predicates`

Register a new predicate in the controlled vocabulary.

Returns `201 Created` on success.

<ParamField body="predicate_id" type="string" required>
  Unique predicate identifier (e.g., `works_at`, `located_in`). Use snake\_case.
</ParamField>

<ParamField body="description" type="string">
  Human-readable description of the predicate's semantics.
</ParamField>

<CodeGroup>
  ```bash Request theme={null}
  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"
    }'
  ```

  ```json Response (201) theme={null}
  {
    "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"
  }
  ```
</CodeGroup>

***

## Get Predicate

`GET /v1/predicates/{id}`

Retrieve a single predicate by its record ID, including all alias mappings.

<ParamField path="id" type="string" required>
  Predicate registry record ID (e.g., `predicate_registry:550e8400-...`).
</ParamField>

<CodeGroup>
  ```bash Request theme={null}
  curl http://localhost:3000/v1/predicates/predicate_registry:550e8400-e29b-41d4-a716-446655440000 \
    -H "Authorization: Bearer $TOKEN"
  ```

  ```json Response theme={null}
  {
    "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"
      }
    ]
  }
  ```
</CodeGroup>

***

## 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.

<ParamField path="id" type="string" required>
  Predicate registry record ID.
</ParamField>

<ParamField body="alias" type="string" required>
  The alias string (e.g., `employed_by`).
</ParamField>

<ParamField body="alias_type" type="string" default="raw_string">
  Type of alias. One of: `raw_string`, `plugin_code`, `schema_field`.
</ParamField>

<ParamField body="confidence" type="number" default="0.9">
  Confidence score for the alias mapping (0.0 to 1.0).
</ParamField>

<ParamField body="scope" type="string" default="global">
  Scope of the alias. One of: `global`, `plugin_only`, `source_type`.
</ParamField>

<ParamField body="source_plugin" type="string">
  Source plugin identifier if the alias was generated by a plugin.
</ParamField>

<CodeGroup>
  ```bash Request theme={null}
  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
    }'
  ```

  ```json Response (201) theme={null}
  {
    "id": "predicate_alias:bbb...",
    "alias": "employed_by",
    "alias_type": "raw_string",
    "predicate_id": "works_at",
    "confidence": 0.95,
    "status": "proposed"
  }
  ```
</CodeGroup>

***

## Update Alias Status

`PATCH /v1/predicates/{id}/aliases/{alias_id}`

Activate or deprecate a predicate alias.

<ParamField path="id" type="string" required>
  Predicate registry record ID.
</ParamField>

<ParamField path="alias_id" type="string" required>
  Predicate alias record ID (e.g., `predicate_alias:bbb...`).
</ParamField>

<ParamField body="status" type="string" required>
  New alias status. One of: `proposed`, `active`, `deprecated`.
</ParamField>

<CodeGroup>
  ```bash Request theme={null}
  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"}'
  ```

  ```json Response theme={null}
  {
    "id": "predicate_alias:bbb...",
    "alias": "employed_by",
    "status": "active",
    "confidence": 0.95
  }
  ```
</CodeGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.