Skip to main content
POST
/
digester
/
{session_id}
/
relations
Extract Relations
curl --request POST \
  --url https://api.example.com/digester/{session_id}/relations \
  --header 'Content-Type: application/json' \
  --data '
{
  "relations": {}
}
'
{
  "jobId": "<string>",
  "status": "<string>",
  "result": {
    "result.relations": [
      {
        "result.relations[].name": "<string>",
        "result.relations[].shortDescription": "<string>",
        "result.relations[].subject": "<string>",
        "result.relations[].subjectAttribute": "<string>",
        "result.relations[].object": "<string>",
        "result.relations[].objectAttribute": "<string>"
      }
    ]
  },
  "message": "<string>",
  "sessionId": "<string>",
  "status_code": 123,
  "detail": "<string>"
}
Extract relations between object classes from documentation. Relations represent connections like “User has Groups”, “Group has Members”, etc.
You must extract object classes first using /classes endpoint before extracting relations.

​
Request

​
session_id
string
required
Session ID (UUID format)
​
use_previous_session_data
boolean
default:"true"
Whether to use previous session data if available

​
Response

Returns a job ID to poll for results.
​
jobId
string
Job ID (UUID) to track extraction progress

​
Example Request

curl -X POST "https://api.example.com/digester/550e8400-e29b-41d4-a716-446655440000/relations" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Example Response

{
  "jobId": "123e4567-e89b-12d3-a456-426614174000"
}

​
Get Relations Status

Get the status and results of the relations extraction job.

​
Request

​
session_id
string
required
Session ID (UUID format)
​
jobId
string
Job ID (optional, will use session’s job if not provided)

​
Response

​
status
string
Job status: pending, running, finished, or failed
​
result
object
Extraction results (available when status is finished)
​
result.relations
array
List of discovered relations between object classes
​
result.relations[].name
string
Human-readable name of the relation (e.g., “User to Group”, “Account to User”)
​
result.relations[].shortDescription
string
Short description or summary of the relationship
​
result.relations[].subject
string
Normalized lowercase name of the subject class (owner of the attribute)
​
result.relations[].subjectAttribute
string
Exact property name on the subject that establishes the relation
​
result.relations[].object
string
Normalized lowercase name of the object class being referenced
​
result.relations[].objectAttribute
string
Exact back-reference property name on the object class (if documented)

​
Example Request

curl -X GET "https://api.example.com/digester/550e8400-e29b-41d4-a716-446655440000/relations?jobId=123e4567-e89b-12d3-a456-426614174000" \
  -H "Authorization: Bearer YOUR_TOKEN"

​
Example Response

{
  "status": "finished",
  "result": {
    "relations": [
      {
        "name": "User to Groups",
        "shortDescription": "A user can belong to multiple groups for access control",
        "subject": "user",
        "subjectAttribute": "groups",
        "object": "group",
        "objectAttribute": "members"
      },
      {
        "name": "User to Roles",
        "shortDescription": "A user can have multiple roles assigned",
        "subject": "user",
        "subjectAttribute": "roles",
        "object": "role",
        "objectAttribute": "users"
      },
      {
        "name": "Group to Parent Group",
        "shortDescription": "A group can have a parent group for hierarchical organization",
        "subject": "group",
        "subjectAttribute": "parentGroup",
        "object": "group",
        "objectAttribute": "childGroups"
      },
      {
        "name": "Role to Permissions",
        "shortDescription": "A role defines a set of permissions",
        "subject": "role",
        "subjectAttribute": "permissions",
        "object": "permission",
        "objectAttribute": ""
      },
      {
        "name": "User to Manager",
        "shortDescription": "A user can have a manager who is also a user",
        "subject": "user",
        "subjectAttribute": "manager",
        "object": "user",
        "objectAttribute": "directReports"
      }
    ]
  }
}

​
Override Relations

Manually override the relations data for the session.

​
Request

​
session_id
string
required
Session ID (UUID format)
​
relations
object
required
Relations data as JSON object

​
Response

​
message
string
Success message
​
sessionId
string
Session ID

​
Example Request

curl -X PUT "https://api.example.com/digester/550e8400-e29b-41d4-a716-446655440000/relations" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "relations": [
      {
        "name": "User to Groups",
        "shortDescription": "User membership in groups",
        "subject": "user",
        "subjectAttribute": "groups",
        "object": "group",
        "objectAttribute": "members"
      }
    ]
  }'

​
Example Response

{
  "message": "Relations overridden successfully",
  "sessionId": "550e8400-e29b-41d4-a716-446655440000"
}

​
Relation Types

Relations can represent various types of relationships:
  • One-to-Many: User has many Groups
  • Many-to-Many: Users have many Roles, Roles have many Users
  • Self-referential: User has a Manager (also a User), Group has Parent Group
  • Embedded: User has Profile (embedded object, not a separate class)

​
Understanding Subject and Object

In each relation:
  • Subject: The “owner” of the relationship - the class that has the attribute
  • Object: The “target” of the relationship - the class being referenced
Example: In “User to Groups”
  • Subject: user (has the groups attribute)
  • Object: group (is referenced by the groups attribute)

​
Error Responses

​
status_code
number
HTTP status code
​
detail
string
Error message

​
Common Errors

404 Not Found - No object classes found in session 
{
  "detail": "No object classes found in session. Please run /classes endpoint first."
}

Build docs developers (and LLMs) love

Get started for freeTalk to us