Working with resources

Working with resources

Most VerifyWise resources (projects, risks, vendors, models, tasks and more) follow the same REST pattern: list them, fetch one by id, create, update and delete. Once you know the pattern, every resource works the same way. The few places where they differ are listed at the end.

This article assumes you already have a token and know the base URL. If not, read the Platform REST API article first.

The CRUD pattern

Using vendors as the example, here is the full set of operations. Every request carries your bearer token.

List and get

curl "http://localhost:3000/api/vendors" \
  -H "Authorization: Bearer <your-token>"

The response is the standard envelope. The list lives in the data field:

{
  "message": "OK",
  "data": [
    { "id": 1, "vendor_name": "Acme AI", "website": "https://acme.example" }
  ]
}

Fetch a single vendor by adding its id to the path:

curl "http://localhost:3000/api/vendors/1" \
  -H "Authorization: Bearer <your-token>"

Create

Send the resource fields as a JSON body. For a vendor, the common fields are:

curl -X POST "http://localhost:3000/api/vendors" \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_name": "Acme AI",
    "vendor_provides": "LLM hosting",
    "website": "https://acme.example",
    "vendor_contact_person": "Jane Doe",
    "review_status": "Not started"
  }'

The response returns the created vendor with its assigned id. Each resource has its own set of fields, so check the resource in the live reference at /api/docs to see exactly what it accepts.

Update and delete

Update sends only the fields you want to change. Delete needs no body.

curl -X PATCH "http://localhost:3000/api/vendors/1" \
  -H "Authorization: Bearer <your-token>" \
  -H "Content-Type: application/json" \
  -d '{ "review_status": "In review" }'

curl -X DELETE "http://localhost:3000/api/vendors/1" \
  -H "Authorization: Bearer <your-token>"

Where resources differ

The pattern is consistent, but three details vary by resource. Always confirm them per resource in /api/docs before you wire up an integration.

Path casing

Most paths are lowercase (/api/vendors, /api/projects), but some keep camelCase. Project risks are served at /api/projectRisks, not /api/project-risks. Use the path exactly as the reference shows it.

Update verb (PATCH vs PUT)

The update verb is not the same for every resource. Sending the wrong one returns a 404 or 405.

The filter parameter

Some list endpoints accept a filter query parameter, and some do not. Project risks support it; projects and vendors do not. When supported, the values are active (the default), deleted or all.

curl "http://localhost:3000/api/projectRisks?filter=all" \
  -H "Authorization: Bearer <your-token>"

Roles and access

Every resource endpoint requires a valid token. Most read and write operations are open to any role within your organization, but some actions are restricted. For example, the bulk update of project risks (PATCH /api/projectRisks/bulk) is limited to Admin and Editor. A token carries the role of the user who created it, so an integration that needs to bulk-update risks must use a key created by an Admin or Editor.

Two reminders