API Examples

Create a key in Administration > Settings > API & MCP. Give it only the permissions your integration needs.

Check the connection

Set the instance URL and your key in the environment:

export VULNOTES_URL="https://your-instance.vulnotes.app"
export VULNOTES_API_KEY="vuln_sk_your_key"

curl --fail-with-body "$VULNOTES_URL/api/api-keys/me" \
  -H "X-API-Key: $VULNOTES_API_KEY"

The response lists the key's effective permissions. These include the limits of its owner's current roles; a key cannot exceed its owner.

List reports

With ro:reports:

curl --fail-with-body \
  "$VULNOTES_URL/api/reports?page=1&limit=25" \
  -H "X-API-Key: $VULNOTES_API_KEY"

Paginated endpoints return a response envelope. Check its pagination fields before requesting the next page. Without pagination parameters, some endpoints return a plain array, so do not assume every list has the same shape.

For a script that needs all visible reports, the SDK handles the pages:

from vulnotes import VulnotesClient

with VulnotesClient() as client:
    for report in client.reports.iter(limit=100):
        print(report["_id"], report["title"])

Handle errors

Status	What to check
400 / 422	Request fields, IDs, supported values, and validation details
401	Missing, invalid, disabled, or regenerated key
403	Missing scope, account permissions, or unavailable feature
404	Missing resource or one hidden by access restrictions
409	A conflicting update; reread the resource before retrying
429	Request limit; wait before retrying

For write requests, confirm whether the previous request succeeded before sending it again. A repeated create can produce another report or attachment.

Continue with the Reports API, Attachments API, or full reference.