Build on Gigvora

Authentication

Create a key in Settings → Integrations (organisation keys: Organisation → Settings → Integrations, owners and admins). The key is shown once; Gigvora stores only a SHA-256 hash. Send it as a Bearer token — never in a URL.

curl https://<your-gigvora-host>/api/v1/search?q=react&limit=5 \
  -H "Authorization: Bearer gvk_…"

• Keys expire (7–365 days), can be revoked instantly, and record when they were last used.
• Every request runs as the key's owner under the same row-level security as their own session — a key can never see more than its owner.
• Organisation keys stop working if their creator stops being an owner or admin; any key stops if its owner's account is restricted.
• OAuth ("Sign in with Gigvora") and service accounts aren't available yet.

API reference (v1)

JSON over HTTPS. Successful responses are { data, next_cursor?, api_version }. The machine-readable description is at /api/v1/openapi.json (OpenAPI 3.1).

• Pagination: pass next_cursor back as cursor. Cursors are opaque.
• Idempotency: send Idempotency-Key on POST /api/v1/agent-runs; repeats within 24 hours return the first response with Idempotent-Replayed: true.
• Mass assignment: only documented parameters are read; anything else is ignored.
• Deprecation: v1 fields are only added, never removed or renamed. A breaking change ships as v2 with at least 90 days' notice in the changelog.
• SDKs: there's no official SDK yet — generate a client from the OpenAPI document or call the endpoints directly.

Errors and rate limits

Errors are { "error": { "type", "message", "request_id" }, "api_version" }. Each key may make 60 requests per minute (REST and MCP combined); responses carry RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset, and a 429 carries Retry-After.

MCP server and tool catalogue

POST /api/mcp speaks the Model Context Protocol over Streamable HTTP (protocol versions 2025-06-18, 2025-03-26 and 2024-11-05; JSON responses, no server-sent stream). Authenticate with an API key; tools/list returns only the tools that key's scopes allow, so revoking a scope or the key removes them. Every tool call is traced in your request log.

{
  "mcpServers": {
    "gigvora": {
      "type": "http",
      "url": "https://<your-gigvora-host>/api/mcp",
      "headers": { "Authorization": "Bearer gvk_…" }
    }
  }
}

Not available yet: money movement (checkout, payouts, refunds) and approving agent actions or organisation approvals — those are always made by people inside Gigvora.

Webhooks

Add HTTPS endpoints in Settings → Integrations. Each delivery is a POST with a JSON body { id, type, api_version: "2026-10-22", created_at, organisation_id?, data } and headers Gigvora-Signature, Gigvora-Event-Id, Gigvora-Event-Type, Gigvora-Delivery-Id and Gigvora-Delivery-Attempt.

• Payloads carry ids, kinds and statuses only (no prices, messages or cover letters) — fetch details through the API with the right scope.
• Answer 2xx within 10 seconds. Anything else is retried with exponential backoff (8 attempts over about an hour), then marked dead; you can redeliver from the log.
• Five dead deliveries in a row, or a 410 Gone, disable the endpoint until you re-enable it. At most 60 deliveries per minute go to one endpoint.
• Use the event id to ignore duplicates, and reject signatures older than 5 minutes to stop replays.
• Rotating the secret keeps the old one signing (as a second v1) for 24 hours.
• Endpoints must be public: private, loopback and link-local addresses are refused when you save and again on every delivery. Redirects aren't followed.

Verifying a signature (Node.js):

import crypto from "node:crypto";

// header = req.headers["gigvora-signature"]   e.g. "t=1792650000,v1=ab12…[,v1=…]"
export function verifyGigvora(rawBody, header, secret, toleranceSec = 300) {
  const items = header.split(",").map((p) => p.trim().split("="));
  const t = Number(items.find(([k]) => k === "t")?.[1]);
  const sigs = items.filter(([k]) => k === "v1").map(([, v]) => v);
  if (!t || Math.abs(Date.now() / 1000 - t) > toleranceSec) return false; // replay window
  const expected = crypto.createHmac("sha256", secret).update(`${t}.${rawBody}`).digest("hex");
  return sigs.some((s) => s.length === expected.length && crypto.timingSafeEqual(Buffer.from(s), Buffer.from(expected)));
}

Zapier, Make and your CRM

Connect Gigvora to thousands of apps without writing code: webhooks trigger your automation, the API acts back.

1. Trigger. In Zapier choose Webhooks by Zapier → Catch Hook (in Make: Webhooks → Custom webhook) and copy the URL it gives you.
2. Subscribe. In Gigvora go to Settings → Integrations → Webhooks, add that URL and pick events such as message.received, quote.requested, payment.succeeded, client.created or notification.created (covers every alert). Send a test event so Zapier/Make learns the payload shape.
3. Act back. Create an API key with only the scopes you need (for example clients:write or messages:write) and call the API from a Webhooks → Custom request / HTTP step with Authorization: Bearer gvk_…. Send an Idempotency-Key header so retries never act twice.
4. Verify. For your own servers, check the Gigvora-Signature header (above). Zapier and Make hook URLs work like passwords — keep them private and rotate them if they leak.

CRM. HubSpot and Pipedrive connect directly in Settings → Integrations → CRM (paste a private-app or API token; clients are pushed within minutes). For Salesforce, Zoho or anything else, use the recipe above with client.created and GET /api/v1/clients?updated_since=… for incremental sync.

Calendars. Settings → Integrations → Create a feed link gives a private .ics URL that Google Calendar, Outlook and Apple Calendar subscribe to (read-only, hourly).

Changelog

• 22 October 2026 — v1. API keys with scopes, REST endpoints above, MCP server, outgoing webhooks.

Use of the API is covered by our Terms and Acceptable Use Policy. Dedicated Developer and API Terms haven't been published yet.