API & webhooks

Authentication

Owners and admins create keys in Settings → Developers. A key is shown once; store it as a secret. Keys are read-only unless you allow writes, and they act as the person who created them (their role applies, and the key stops working if they leave the workspace).

curl https://your-torvany.example/api/v1/me \
  -H "Authorization: Bearer pw_live_xxxxxxxx_…"

Endpoints

Working with tasks

Refer to people by email, statuses by name, and custom fields by their name and option labels. Dates are YYYY-MM-DD. Send an Idempotency-Key header on POST to make retries safe (replays return the first response for 24 hours).

curl -X POST https://your-torvany.example/api/v1/projects/WEB/tasks \
  -H "Authorization: Bearer $TORVANY_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: deal-4821" \
  -d '{
    "title": "Kick-off with Acme",
    "status": "To do",
    "assignee": "[email protected]",
    "priority": "high",
    "due_date": "2026-11-03",
    "fields": { "Type": "Feature" }
  }'

Responses wrap data: lists return { "data": [...], "next_cursor": "…" | null }; single items return { "data": { … } }.

Recurring tasks

Send recurrence on create or PATCH to make a task repeat, or null to stop. When it's completed, the next occurrence is created (you'll get task.created) and the rule moves to it. freq is daily, weekly, monthly or yearly; weekly rules list weekdays (0 = Sunday); basis is schedule (from the due date) or completion; ends is never, on a date, or after a number of times. Tasks return the rule with a readable summary, plus series.

curl -X PATCH https://your-torvany.example/api/v1/tasks/OPS-12 \
  -H "Authorization: Bearer $TORVANY_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "recurrence": { "freq": "weekly", "interval": 1, "weekdays": [1], "ends": { "type": "after", "count": 10 } } }'

Webhooks

Add an HTTPS endpoint in Settings → Developers and choose events. We POST JSON within seconds and retry failures after 1 minute, 5 minutes, 30 minutes, 2 hours and 6 hours. After 15 failures in a row the endpoint is disabled and admins are emailed. Respond with any 2xx within 10 seconds.

• task.createdA task was created (in the app, by import or through the API).
• task.updatedFields changed. data.changed lists them (title, status, assignee, …).
• task.completedA task entered a Done status (also sent as task.updated).
• task.deletedA task was moved to the trash. data.task is the last snapshot.
• task.restoredA task came back from the trash. data.task is the restored task.
• comment.createdA comment was added. Mentions appear as @Name.
• project.createdA project was created.
• project.archivedA project was archived.
• form.submittedSomeone submitted a request form. data has form, task (id, key, title) and submitter (email, name).

{
  "id": "evt_8f3a…",
  "type": "task.updated",
  "created_at": "2026-10-02T09:30:00.000Z",
  "workspace": { "id": "…", "slug": "acme-inc", "name": "Acme Inc" },
  "data": { "task": { "key": "WEB-12", "title": "…", "status": "In progress", … }, "changed": ["status"] }
}

Verifying signatures

Each request has Torvany-Signature: t=<unix seconds>,v1=<hex>, where v1 is HMAC-SHA256 of t + "." + raw body with your endpoint's secret. Reject requests older than 5 minutes. Torvany-Event and Torvany-Delivery headers identify the event and attempt; use the event id to ignore duplicates.

// Node.js
import crypto from "node:crypto";
function verify(secret, rawBody, header) {
  const { t, v1 } = Object.fromEntries(header.split(",").map((p) => p.split("=")));
  if (Math.abs(Date.now() / 1000 - Number(t)) > 300) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(v1));
}

# Python
import hmac, hashlib, time
def verify(secret: str, raw_body: bytes, header: str) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    if abs(time.time() - int(parts["t"])) > 300:
        return False
    expected = hmac.new(secret.encode(), f'{parts["t"]}.'.encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])

Errors & limits

Errors look like { "error": { "code": "validation_failed", "message": "…", "field": "status" } }. Every response carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset.

• 400 bad_json / bad_requestThe body isn't valid JSON, or a parameter is malformed.
• 401 unauthorizedMissing, invalid, revoked or expired key, or its owner left the workspace.
• 402 plan_required / plan_limitThe plan doesn't include the API, or a plan limit was reached.
• 403 insufficient_scope / forbiddenA read-only key tried to write, or the key's owner lacks permission.
• 404 not_foundNo such project or task in this workspace.
• 409 idempotency_conflictAn Idempotency-Key was reused with a different request.
• 422 validation_failedInvalid input; error.field says which.
• 429 rate_limitedMore than 120 requests a minute for this key. See Retry-After.