---
# @generated by sylphx-gen 0.1.0 from contracts@fb95f0c42a0ec5d8e3cb694c0054b529c0b24b184112c65ef60c9044b4ce61f9. Do not edit.
title: "Relations"
description: "The `relations` collection of Sylphx Knowledge: A Relation is a fact: a typed, directed edge between two entities, or a value about one entity."
type: reference
product: knowledge
summary: "A Relation is a fact: a typed, directed edge between two entities, or a value about one entity."
updated: 2026-09-28
order: 900
---

A Relation is a fact: a typed, directed edge between two entities, or a value about one entity. Facts are bi-temporal: `valid_start_time` and `valid_end_time` say when it holds in the world, `create_time` and `supersede_time` when it was learned and replaced. A change closes the old fact; nothing is overwritten. Every fact cites at least one episode.

**Service** Sylphx Knowledge · **Resource type** `knowledge.sylphx.com/Relation` · **Name pattern** `orgs/{org}/projects/{project}/envs/{env}/spaces/{space}/relations/{relation}` · **Shape** `record`

**Not available yet.** Sylphx Knowledge is declared in the registry but no backend serves it: every call answers `501` with the problem code `UNIMPLEMENTED`.

## Fields

| Field | Type | What it is |
| --- | --- | --- |
| `name` | `string` | `orgs/{org}/projects/{project}/envs/{env}/spaces/{space}/relations/{relation}`. |
| `uid` | `string` | `krel_<26 base32>`; never reused. Output only. |
| `meta` | `ResourceMeta` | Resource metadata. |
| `subject` | `string` | The entity the fact is about. Required. |
| `predicate` | `string` | The relation type, snake_case, for example `works_at` or `prefers`; a core predicate or one of an accepted Knowledge Schema. Required. |
| `object` | `string` | The other entity, for an edge. A fact has `object`, `value`, or both. |
| `value` | `value` | The value, for a fact about one entity. |
| `statement` | `string` | The fact as one sentence, used for search and shown with citations. |
| `valid_start_time` | `timestamp` | When the fact starts to hold in the world; default when it was recorded. |
| `valid_end_time` | `timestamp` | When the fact stopped holding in the world; unset while it holds. |
| `episodes` | `string[]` | The episodes the fact comes from. A structured write with none records its own episode and cites it; an extracted fact cites the episodes it was read from. |
| `provenance` | `Provenance` | Where it came from and who wrote it. Output only. |
| `successor` | `string` | The fact that replaced this one, once it is superseded. Output only. |
| `create_time` | `timestamp` | When the fact was recorded. Output only. |
| `supersede_time` | `timestamp` | When the fact was replaced by a newer record; unset while current. Output only. |

## Methods

Every method of the collection, in the registry's order, with the scope it
needs. The full request, response and examples are one link away.

| Method | Call | What it does |
| --- | --- | --- |
| `GET` | [`get`](/docs/api/relations#get) | Gets a relation. |
| `GET` | [`list`](/docs/api/relations#list) | Lists a space's facts. The filter is limited to `subject`, `predicate`, `object` and `provenance.channel`; superseded facts are listed only with `show_superseded`. |
| `POST` | [`create`](/docs/api/relations#create) | Records a fact in a space (`relate`). A fact that contradicts a current one with the same subject and a single-valued predicate closes the older fact; nothing is overwritten. |
| `DELETE` | [`delete`](/docs/api/relations#delete) | Deletes a fact. Deletion is for data that must go; a fact that stopped being true is closed with `:close`. |
| `POST` | [`close`](/docs/api/relations#close) | Closes a fact (`close_fact`): it stopped holding in the world at `valid_end_time`. The fact stays readable for questions about the time before the close. |

## get

Gets a relation.

`GET https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/spaces/space/relations/relation` · scope `knowledge:read` · effect `read` · not available yet · [Request, response and examples](/docs/api/relations/get)

## list

Lists a space's facts. The filter is limited to `subject`, `predicate`, `object` and `provenance.channel`; superseded facts are listed only with `show_superseded`.

`GET https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/spaces/space/relations` · scope `knowledge:read` · effect `read` · not available yet · paginated · [Request, response and examples](/docs/api/relations/list)

## create

Records a fact in a space (`relate`). A fact that contradicts a current one with the same subject and a single-valued predicate closes the older fact; nothing is overwritten.

`POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/spaces/space/relations` · scope `knowledge:write` · effect `write` · not available yet · [Request, response and examples](/docs/api/relations/create)

## delete

Deletes a fact. Deletion is for data that must go; a fact that stopped being true is closed with `:close`.

`DELETE https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/spaces/space/relations/relation` · scope `knowledge:write` · effect `destructive` · not available yet · [Request, response and examples](/docs/api/relations/delete)

## close

Closes a fact (`close_fact`): it stopped holding in the world at `valid_end_time`. The fact stays readable for questions about the time before the close.

`POST https://api.sylphx.com/v1/orgs/acme/projects/shop/envs/production/spaces/space/relations/relation:close` · scope `knowledge:write` · effect `write` · not available yet · [Request, response and examples](/docs/api/relations/close)