API reference

Every endpoint an API key can reach: 9 of them, all read-only.

New here? Start with the integration guide. Prefer a machine-readable version? Download the OpenAPI document and import it into Postman, Insomnia or a client generator.

Base URL and authentication

Base URL	`https://api.samloryx.co.za`
Authentication	`X-API-Key: slx_…` or `Authorization: Bearer slx_…` on every request
Methods	`GET` only. Any other method with a key is refused with `403`.
Format	JSON. Lists are plain arrays, newest first, at most 200 rows.
Data returned	Only the company the key belongs to.

Each endpoint below names the one scope it requires. A key without that scope gets 403, and the response says which scope is missing.

Errors

Every error is application/problem+json with these fields. The guide says what to do about each status.

Field	Type	Description
`type`	string	Always about:blank.
`title`	string	The HTTP reason phrase.
`status`	integer	The HTTP status code.
`detail`	string	What went wrong, in words.
`correlationId`	string	Quote this when asking for help; it finds the request in our logs.
`timestamp`	timestamp	When the error happened (UTC).

Identity

Check the key and see which products the company runs.

GET/api/v1/mescope: workspaces.read

Who this key is

Returns the key's name, the company it belongs to and the scopes it was granted. Call it first: a 200 here means the key is valid and tells you what it can reach.

Query parameters

None.

Response: one object with these fields

Field	Type	Description
`email`	string	Present only when a person is signed in. Never present for an API key.
`displayName`	string	The key's name, as given when it was created.
`tenant`	string	The company the key belongs to. Every response is limited to this company's data.
`roles`	array of string	Always ["API"] for a key.
`scopes`	array of string	The scopes granted to the key.

Example

Request

curl "https://api.samloryx.co.za/api/v1/me" \
  -H "X-API-Key: $SAMLORYX_API_KEY"

200 OK (illustrative values)

{
  "displayName": "Accounting sync",
  "tenant": "Thabeng Civils",
  "roles": [
    "API"
  ],
  "scopes": [
    "graph.read",
    "workspaces.read"
  ]
}

GET/api/v1/workspacesscope: workspaces.read

List workspaces

One workspace per product the company has. Use it to find out which industry products are present before reading their data.

Query parameters

None.

Response: an array of objects with these fields

Field	Type	Description
`id`	uuid	Workspace id.
`productKey`	string	Which product this workspace is for.One of: CONSTRUCT, PROPERTY, PROFESSIONAL, FINANCIAL_SERVICES, GROWTH
`name`	string	Display name.

Example

Request

curl "https://api.samloryx.co.za/api/v1/workspaces" \
  -H "X-API-Key: $SAMLORYX_API_KEY"

200 OK (from the synthetic demo company)

[
  {
    "id": "c0a80000-0000-4000-8000-000000000011",
    "productKey": "CONSTRUCT",
    "name": "Construct AI"
  },
  {
    "id": "c0a80000-0000-4000-8000-000000000015",
    "productKey": "GROWTH",
    "name": "Growth AI"
  }
]

Business Graph

The company's shared record: who it deals with, where it works, what it holds and what it owes.

GET/api/v1/graph/companiesscope: graph.read

List companies

The organisations this company deals with: clients, public buyers, suppliers and subcontractors.

Query parameters

Name	Type	Description
`limit`	integer, optional	How many rows to return, newest first. 1 to 200; values outside that range are clamped, not rejected. Default 100.

Response: an array of objects with these fields

Field	Type	Description
`id`	uuid	Company id.
`name`	string	Trading or registered name.
`registrationNumber`	string	Company registration number, when recorded.
`kind`	string	The relationship to the account holder.One of: CLIENT, BUYER, SUPPLIER, SUBCONTRACTOR, OTHER
`notes`	string	Free text.
`createdAt`	timestamp	When the record was created (UTC).

Example

Request

curl "https://api.samloryx.co.za/api/v1/graph/companies?limit=1" \
  -H "X-API-Key: $SAMLORYX_API_KEY"

200 OK (from the synthetic demo company)

[
  {
    "id": "c0a80000-0000-4000-8000-000000000031",
    "name": "Kopano Developments",
    "registrationNumber": "2014/123456/07",
    "kind": "CLIENT",
    "notes": "Fictional property developer client (synthetic demo data).",
    "createdAt": "2026-08-16T13:17:15.889594Z"
  }
]

GET/api/v1/graph/documentsscope: graph.read

List documents

Document records: title, kind, expiry and provenance. This returns the record, not the file; file contents are not available to API keys in v1.

Query parameters

Name	Type	Description
`limit`	integer, optional	How many rows to return, newest first. 1 to 200; values outside that range are clamped, not rejected. Default 100.

Response: an array of objects with these fields

Field	Type	Description
`id`	uuid	Document id.
`title`	string	Document title.
`kind`	string	What sort of document it is.One of: CONTRACT, TENDER_PACK, CERTIFICATE, INVOICE, OTHER
`sourceUri`	string	Where the document came from, when recorded.
`sha256`	string	SHA-256 of the stored file, when a file is attached. Use it to confirm a copy is the same file.
`expiresOn`	date	Expiry date, for documents that lapse (certificates, for example).
`companyId`	uuid	Related company, when linked.
`siteId`	uuid	Related site, when linked.
`createdAt`	timestamp	When the record was created (UTC).

Example

Request

curl "https://api.samloryx.co.za/api/v1/graph/documents?limit=1" \
  -H "X-API-Key: $SAMLORYX_API_KEY"

200 OK (from the synthetic demo company)

[
  {
    "id": "c0a80000-0000-4000-8000-000000000036",
    "title": "Tender pack CB 112/2026",
    "kind": "TENDER_PACK",
    "sourceUri": null,
    "sha256": null,
    "expiresOn": null,
    "companyId": "c0a80000-0000-4000-8000-000000000032",
    "siteId": null,
    "createdAt": "2026-08-16T13:17:15.889594Z"
  }
]

GET/api/v1/graph/obligationsscope: graph.read

List obligations

Things the company must do or is owed: compliance duties, contractual deadlines, payments.

Query parameters

Name	Type	Description
`limit`	integer, optional	How many rows to return, newest first. 1 to 200; values outside that range are clamped, not rejected. Default 100.

Response: an array of objects with these fields

Field	Type	Description
`id`	uuid	Obligation id.
`title`	string	What must be done.
`kind`	string	The nature of the duty.One of: COMPLIANCE, CONTRACTUAL, PAYMENT, OTHER
`dueOn`	date	Due date, when there is one.
`status`	string	OPEN until it is completed.One of: OPEN, DONE
`amount`	decimal	Money involved, when there is any. A decimal number, not cents.
`currency`	string	ISO 4217 code for amount. ZAR unless stated.
`companyId`	uuid	The counterparty, when linked.
`documentId`	uuid	The document the obligation comes from, when linked.
`notes`	string	Free text.
`createdAt`	timestamp	When the record was created (UTC).

Example

Request

curl "https://api.samloryx.co.za/api/v1/graph/obligations?limit=1" \
  -H "X-API-Key: $SAMLORYX_API_KEY"

200 OK (from the synthetic demo company)

[
  {
    "id": "c0a80000-0000-4000-8000-000000000038",
    "title": "Retention payment, Ward 4 road",
    "kind": "PAYMENT",
    "dueOn": "2026-10-15",
    "status": "OPEN",
    "amount": 240000,
    "currency": "ZAR",
    "companyId": "c0a80000-0000-4000-8000-000000000031",
    "documentId": null,
    "notes": null,
    "createdAt": "2026-08-16T13:17:15.889594Z"
  }
]

GET/api/v1/graph/personsscope: graph.read

List people

Contacts, each optionally attached to a company. This is personal information: store and use it only for the purpose the company authorised.

Query parameters

Name	Type	Description
`limit`	integer, optional	How many rows to return, newest first. 1 to 200; values outside that range are clamped, not rejected. Default 100.

Response: an array of objects with these fields

Field	Type	Description
`id`	uuid	Person id.
`companyId`	uuid	The company this person belongs to, when linked.
`fullName`	string	Full name.
`roleTitle`	string	Job title or role.
`email`	string	Email address, when recorded.
`phone`	string	Phone number, when recorded.
`notes`	string	Free text.
`createdAt`	timestamp	When the record was created (UTC).

Example

Request

curl "https://api.samloryx.co.za/api/v1/graph/persons?limit=1" \
  -H "X-API-Key: $SAMLORYX_API_KEY"

200 OK (from the synthetic demo company)

[
  {
    "id": "c0a80000-0000-4000-8000-000000000033",
    "companyId": "c0a80000-0000-4000-8000-000000000031",
    "fullName": "Naledi Khumalo",
    "roleTitle": "Client contact",
    "email": "[email protected]",
    "phone": "+27 82 555 0101",
    "notes": null,
    "createdAt": "2026-08-16T13:17:15.889594Z"
  }
]

GET/api/v1/graph/sitesscope: graph.read

List sites

Places where work happens: construction sites, properties, offices.

Query parameters

Name	Type	Description
`limit`	integer, optional	How many rows to return, newest first. 1 to 200; values outside that range are clamped, not rejected. Default 100.

Response: an array of objects with these fields

Field	Type	Description
`id`	uuid	Site id.
`companyId`	uuid	The company the site is for, when linked.
`name`	string	Site name.
`province`	string	Province, when recorded.
`address`	string	Street address, when recorded.
`status`	string	Whether work there is planned, under way or finished.One of: ACTIVE, PLANNED, CLOSED
`createdAt`	timestamp	When the record was created (UTC).

Example

Request

curl "https://api.samloryx.co.za/api/v1/graph/sites?limit=1" \
  -H "X-API-Key: $SAMLORYX_API_KEY"

200 OK (from the synthetic demo company)

[
  {
    "id": "c0a80000-0000-4000-8000-000000000034",
    "companyId": "c0a80000-0000-4000-8000-000000000031",
    "name": "Ward 4 access road, Tshwane",
    "province": "Gauteng",
    "address": null,
    "status": "ACTIVE",
    "createdAt": "2026-08-16T13:17:15.889594Z"
  }
]

Tenders

Public tenders matched to the company's profile.

GET/api/v1/tendersscope: tenders.read

List matched tenders

Public tenders scored against the company's profile, best tier first. An empty array means nothing has been matched yet, not an error.

Query parameters

Name	Type	Description
`tier`	string, optional	Only matches in this tier.One of: RECOMMENDED, WORTH_A_LOOK, STRETCH
`decided`	boolean, optional	true returns only tenders a person has decided on; false only those still undecided. Omit for both.
`limit`	integer, optional	How many rows to return, newest first. 1 to 200; values outside that range are clamped, not rejected. Default 100.

Response: an array of objects with these fields

Field	Type	Description
`ocid`	string	Open Contracting ID of the tender. Stable; use it as your key.
`title`	string	Tender title as published.
`buyer`	string	The procuring entity.
`province`	string	Province, when the notice states one.
`closesOn`	date	Closing date (UTC), when published.
`runwayDays`	integer	Days from today to the closing date. Negative once closed; null when no closing date was published.
`score`	integer	Match score. Higher is a closer fit to the company's profile.
`tier`	string	RECOMMENDED, WORTH_A_LOOK, or STRETCH (the required CIDB grade is one above a grade the company holds).One of: RECOMMENDED, WORTH_A_LOOK, STRETCH
`reasons`	array of string	Plain-language reasons for the score.
`briefingNote`	string	Briefing session details, when the notice has any.
`decision`	string	The decision a person recorded, or null if nobody has decided.One of: BID, NO_BID, CLARIFY_FIRST
`analysisRunId`	uuid	The agent run that analysed the tender documents, when one has run.
`docCount`	integer	How many documents the notice lists.

Example

Request

curl "https://api.samloryx.co.za/api/v1/tenders?limit=1" \
  -H "X-API-Key: $SAMLORYX_API_KEY"

200 OK (illustrative values)

[
  {
    "ocid": "ocds-9t57fa-112-2026",
    "title": "CB 112/2026 Rehabilitation of internal roads, Ward 4",
    "buyer": "Mmakau Local Municipality",
    "province": "North West",
    "closesOn": "2026-11-06",
    "runwayDays": 27,
    "score": 82,
    "tier": "RECOMMENDED",
    "reasons": [
      "CIDB grade 6CE held; tender requires 5CE",
      "Province matches operating area"
    ],
    "briefingNote": "Compulsory briefing 21 Oct, 10:00, municipal offices",
    "decision": null,
    "analysisRunId": null,
    "docCount": 4
  }
]

Agents

The catalogue of governed agents and what each is permitted to do.

GET/api/v1/agentsscope: tenders.read

List agents

Every agent in the catalogue with its authority level, the tools it may use and the restricted actions it may attempt. Listing only: agents cannot be invoked with an API key in v1. This endpoint is covered by the tenders.read scope.

Query parameters

None.

Response: an array of objects with these fields

Field	Type	Description
`name`	string	Agent identifier.
`description`	string	What the agent does and what it will not do.
`authority`	string	The highest rung of the authority ladder the agent may act at.One of: OBSERVE, RESEARCH, RECOMMEND, PREPARE, DRAFT, EXECUTE_WITH_APPROVAL, AUTONOMOUS
`tools`	array of string	The tools the agent may call.
`outputType`	string	The schema of what the agent produces.
`restrictedActions`	array of string	Restricted actions the agent may prepare. These are never executed without a person's approval.

Example

Request

curl "https://api.samloryx.co.za/api/v1/agents" \
  -H "X-API-Key: $SAMLORYX_API_KEY"

200 OK (from the synthetic demo company)

[
  {
    "name": "document-intelligence",
    "description": "Reads a business document and extracts obligations, deadlines, amounts and compliance requirements. Every finding carries a verbatim citation from the document; uncited findings are flagged unverified and are never applied.",
    "authority": "RECOMMEND",
    "tools": [
      "document.read"
    ],
    "outputType": "document.findings.v1",
    "restrictedActions": []
  }
]