Instructions Over the API

Instructions are the part of Velatir most worth automating. They are the rules that are specific to your organisation, which means they are also the ones that go stale — a codename stops being secret, a supplier relationship ends, a matter closes — and nobody thinks to remove them. If another system already knows when that happens, it can keep Velatir in step.

Instructions belong to the Data Protector. agentType must be "DataProtection"; other agents do not take instructions, and sending one is rejected with 400.

Endpoints

All five sit under your organisation. Everything below assumes the X-API-Key header from Authentication, and {organisationId} is the id you got from GET /organisations.

Method	Path
`POST`	`/organisations/{organisationId}/instructions`
`GET`	`/organisations/{organisationId}/instructions`
`GET`	`/organisations/{organisationId}/instructions/{instructionId}`
`PATCH`	`/organisations/{organisationId}/instructions/{instructionId}`
`DELETE`	`/organisations/{organisationId}/instructions/{instructionId}`

The Body of an Instruction

These are the same parts described in Instructions, in their wire form.

Field	Type	Notes
`agentType`	string	Required. Always `"DataProtection"`.
`title`	string	Required. Up to 200 characters. This is what a reviewer sees in the dashboard.
`trigger`	object	Required. See below.
`action`	string	Required. `"Allow"` or `"Block"`.
`criticality`	string	Required. `"Low"` or `"High"`. High escalates to a person.
`categoryId`	uuid	Optional. The data category this relates to.
`usedBy`	array of uuid	Optional. Agents to assign it to on creation. List yours with `GET /organisations/{organisationId}/agents`.
`allowRedaction`	boolean	Optional, defaults to `false`. Only valid with a `Regex` or `StringMatch` trigger.

Triggers

The trigger object is tagged by its type field.

Semantic
Regex
String match

Matches by meaning. Best when the wording will vary.

{ "type": "Semantic", "text": "Customer is discussing their account balance" }

Matches a pattern. Exact and fast, best for structured data.

{ "type": "Regex", "pattern": "AKIA[0-9A-Z]{16}", "isCaseSensitive": true }

isCaseSensitive defaults to true.

Matches an exact list of terms. Best for codenames and identifiers.

{ "type": "StringMatch", "values": ["Project Aurora"], "isCaseSensitive": false }

isCaseSensitive defaults to true.

Worked Example: Keeping Confidential Codenames in Step

A common pattern is a rule whose whole lifetime is decided elsewhere. Unannounced work is a good example: while a project is confidential its codename should not reach an AI service, and on the day it launches that rule is just noise that will sit in your dashboard forever. Your roadmap tool already knows both dates. Have it call Velatir.

When the project becomes confidential

curl -X POST https://api.velatir.com/organisations/$ORG_ID/instructions \
  -H "X-API-Key: $VELATIR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "agentType": "DataProtection",
    "title": "Block unannounced codename: Project Aurora",
    "trigger": {
      "type": "StringMatch",
      "values": ["Project Aurora"],
      "isCaseSensitive": false
    },
    "action": "Block",
    "criticality": "High"
  }'

Velatir answers 201 Created with the instruction, including the id you will need later:

{
  "id": "8c41d0b6-3e92-4f77-b5a1-27de6a09c8f3",
  "agentType": "DataProtection",
  "title": "Block unannounced codename: Project Aurora",
  "trigger": {
    "type": "StringMatch",
    "values": ["Project Aurora"],
    "isCaseSensitive": false
  },
  "action": "Block",
  "allowRedaction": false,
  "criticality": "High",
  "categoryId": null,
  "assessmentId": null,
  "usedBy": [],
  "createdAt": "2026-09-14T09:12:44.117Z",
  "updatedAt": "2026-09-14T09:12:44.117Z"
}

Store id against the project in your own system. That is the handle you delete with.

An instruction created with no usedBy exists but is not yet assigned to an agent. Pass the agent ids in usedBy on creation if you want it enforcing straight away, or assign it in the dashboard under Agents → Instructions.

When the project launches

curl -X DELETE https://api.velatir.com/organisations/$ORG_ID/instructions/$INSTRUCTION_ID \
  -H "X-API-Key: $VELATIR_API_KEY"

A successful delete returns 204 No Content, and the instruction is removed from every agent it was assigned to. The rule stops applying to new activity from that point. Traces it already acted on are unaffected — deleting an instruction does not rewrite history.

If the rule changes rather than ends

PATCH takes any subset of the fields. To soften a block to an escalation without touching anything else:

curl -X PATCH https://api.velatir.com/organisations/$ORG_ID/instructions/$INSTRUCTION_ID \
  -H "X-API-Key: $VELATIR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "criticality": "Low" }'

Omitted fields are left alone. Sending "categoryId": null explicitly clears the category.

Listing and Finding Instructions

GET /organisations/{organisationId}/instructions returns a page of instructions:

{
  "items": [],
  "totalCount": 0,
  "page": 1,
  "pageSize": 20
}

Narrow it with query parameters: search, triggerType, action, agentId, and agentType. Page with page and pageSize — pageSize defaults to 20 and is capped at 100.

Velatir does not de-duplicate instructions, and creating one is not idempotent. A retried POST produces a second identical instruction rather than returning the first. If your integration retries, record the id you got back and check for it before creating again.

Limits

An agent holds at most 100 instructions. Creating one with a usedBy that would take an agent past that returns 409 Conflict, naming the agent that is full. This is worth designing for if you create an instruction per record. A pattern that adds rules but never removes them will reach the ceiling; the codename example above stays well clear of it because each rule is deleted when the project launches.

Making It Safe to Re-Run

A few habits make an integration like this survive contact with real systems:

Store the instruction id alongside the record that caused it. Searching by title to find it again breaks the first time someone edits the title in the dashboard.
Treat 404 on delete as success. It means the instruction is already gone, which is the state you wanted.
Handle 409 as a real condition, not a retry. Nothing that returns it becomes true by trying again — the agent is full, or the assessment already produced an instruction.
Name the key for the system that holds it. Every change it makes is attributed to that name in the audit trail.

Instructions

What instructions are and how they behave.

Data Protector

The agent that applies them.

Getting Started

Platform

Velatir for Desktop

Browser extension

Connectors

Agents

Sessions & Traces

Insights

Developers

For Providers

Security & Privacy

Endpoints

The Body of an Instruction

Triggers

Worked Example: Keeping Confidential Codenames in Step

When the project becomes confidential

When the project launches

If the rule changes rather than ends

Listing and Finding Instructions

Limits

Making It Safe to Re-Run

Instructions

Data Protector

​Endpoints

​The Body of an Instruction

​Triggers

​Worked Example: Keeping Confidential Codenames in Step

​When the project becomes confidential

​When the project launches

​If the rule changes rather than ends

​Listing and Finding Instructions

​Limits

​Making It Safe to Re-Run

Instructions

Data Protector

Endpoints

The Body of an Instruction

Triggers

Worked Example: Keeping Confidential Codenames in Step

When the project becomes confidential

When the project launches

If the rule changes rather than ends

Listing and Finding Instructions

Limits

Making It Safe to Re-Run