API and webhooks

The API page is where you manage everything a developer needs to build against Productlane: your Workspace ID, API keys and their scopes, outgoing webhooks and their signing secrets, apps connected over MCP, usage analytics, and any remaining legacy v1 keys. Use the API to sync contacts, conversations, and more.

Where to find it

Settings > API (listed under the Workspace group in the settings sidebar).

The page header has a "How it works" button that opens the public API documentation in a new tab.

Controls on this page

Workspace ID

A copy control at the top of the page. Your Workspace ID identifies this workspace when you call the API. Click the copy button to copy it to the clipboard; a "Workspace ID copied" confirmation appears. You do not pass the Workspace ID on v2 API paths (it is inferred from your bearer key), but some integrations and older tooling still need it.

API keys

This block lists the active v2 API keys for the workspace. Each key authenticates with the public API and carries a set of scopes that limit what it can do.

Each key row shows:

• The creator's avatar with a key badge.

• The key label.

• A scope summary: "full access" for a key with the admin scope, otherwise a count like "3 scopes". Hover the summary to see the exact scopes.

• The key preview (the first characters of the secret, the only part of the secret ever shown again after creation).

• Who created it, how long ago, and when it was last used (or "never used").

New API key

Opens the "Create API key" dialog. The dialog has:

• Label: a required, descriptive name for the key.

• Access: a choice between "Full access" and "Only select permissions...".

  • "Full access" grants the admin scope, which can do everything including managing members and webhooks.

  • "Only select permissions..." reveals grouped scope checkboxes. Enable only the scopes the key needs. The default selection when you switch to custom is "Read threads" (threads:read). The "Create" button stays disabled until at least one scope is checked.

Available scopes, grouped as they appear in the dialog:

• Threads and messaging: threads:read (Read threads), threads:write (Write threads), messages:write (Send messages), comments:write (Post internal comments).

• Contacts and companies: contacts:read, contacts:write, companies:read, companies:write.

• Content: changelogs:read, changelogs:write, docs:read (Read help center), docs:write (Write help center), files:write (Upload files such as images and PDFs), snippets:read, snippets:write.

• Roadmap: projects:read, projects:write, issues:read, issues:write, portal:read (Read public portal and customer portal).

• Agent: agent (Call the A2A agent endpoint at /api/a2a).

• Admin: admin (Full admin: members, webhooks, and all of the above).

When you submit, the key is created and the full secret is shown once on a "Save your key" screen and copied to your clipboard automatically. Store it in a secure location. If you lose it, generate a new key; the secret cannot be shown again.

Revoke

Each key row has a more-actions menu (the "..." button) with a "Revoke" item. Revoking opens a "Revoke API key?" confirmation. Confirming stops the key working immediately, so any integration using it breaks. Revocation cannot be undone.

Webhooks

This block lists the workspace webhooks. A webhook sends an HTTP request to your URL when an entity is created, updated, or deleted.

Each webhook row shows the label, a status dot (green when active, gray when disabled), and the destination URL. Clicking a row opens the read-only webhook detail page.

New webhook

Contacts: image_url

Create (POST /v2/contacts) and update (PATCH /v2/contacts/:id) now accept an optional image_url field to set a contact's avatar.

• Omit the field entirely to let Productlane auto-resolve an avatar from Gravatar.

• Pass a URL string to set a specific avatar image.

• Pass null to clear the stored avatar (on update) or store no avatar (on create).

Opens the "Create webhook" dialog:

• Label: a required name (for example, "Production").

• URL: a required, valid URL where events are delivered.

• Data change events: a grid of resource checkboxes with an "All" checkbox that selects or clears every resource at once. Threads (thread.*) is selected by default. At least one resource must be selected or the "Create" button stays disabled.

The available resources are: Threads, Messages, Comments, Contacts, Companies, Changelogs, Issues, Projects, Customer needs, Docs, Tags, and Members. The picker exposes resource-level patterns only. The exact action (for example thread.created versus thread.updated) travels in the type field of each event payload, so subscribing to a resource covers all of its actions.

On success, a "Webhook created" screen shows the signing secret with a copy button. Use the secret to verify the HMAC-SHA256 signature on incoming events. Click "Done" to close.

Webhook row menu

Each row has a more-actions menu with:

• Edit: opens the webhook edit page.

• Disable / Enable: toggles delivery on or off immediately. A disabled webhook keeps its config but stops receiving events.

• Delete: opens a "Delete webhook?" confirmation. Confirming stops the webhook receiving events and cannot be undone.

Webhook detail page

Opened by clicking a webhook row. This read-only page shows:

• Status: Active or Disabled.

• URL: read-only, with a copy button.

• Signing secret: masked by default, with a reveal (eye) button and a copy button. Rotating the secret is done on the edit page.

• Subscribed events: the resource patterns this webhook listens to, shown as pills.

• Recent deliveries: the last 200 events sent to this webhook. Each delivery row shows a status dot (green succeeded, red failed or dead, gray pending), the event type, the HTTP response status, the time, the attempt number when retried, and the duration in milliseconds. Expanding a delivery reveals the event ID, the full JSON payload, and the response body when present.

The page header's more-actions menu repeats Edit, Enable / Disable, and Delete.

Webhook edit page

Opened from any webhook's Edit action. This page uses an explicit Save (it does not auto-save):

• Label: editable, with a copy button.

• URL: editable, validated as an http or https URL, with a copy button.

• Signing secret: read-only, masked, with reveal, copy, and rotate buttons. Rotating opens a "Rotate signing secret?" confirmation; the current secret stops working immediately, so receivers verifying with the old secret reject events until you update them. After rotating, the new secret is revealed so you can copy it.

• Events: the same resource checkboxes as the create dialog. At least one resource must stay selected.

• Save webhook: persists all changes. It is enabled only when there are unsaved changes and the form is valid.

• Reset: appears when there are unsaved changes and reverts the form to the last saved values.

Connected apps

Lists apps authorized to access this workspace over MCP, with one entry per person who connected. Each row shows the app name, who connected it, when it was granted, and when it was last used. The more-actions menu has "Revoke access", which opens a "Revoke connection?" confirmation. Revoking stops that person's connection to the app immediately; they can reconnect by authorizing again. Clicking the connector's name jumps to that member in Members.

API analytics

Appears once the workspace has at least one active API key or one webhook. It charts usage and errors across all keys and webhooks:

• API requests: successful versus failed requests per day.

• API error distribution: errors broken down by endpoint.

• Event deliveries: webhook deliveries by status (succeeded, failed, dead, pending).

• Response time: P95 latency for API requests and webhook deliveries.

A time-window dropdown in the top right switches between "Last 24 hours", "Last 7 days", and "Last 14 days". The default is the last 14 days.

Legacy API keys

Appears only if the workspace still has v1 (legacy) keys. It is a collapsible "Legacy API keys" section with a count. Inside, a warning notes that v1 is deprecated and will be sunset on November 20, 2026, and links to the migration guide. Each legacy key shows its name, a "v1" pill, its key prefix, and its creation date, with a trash button to delete it. Deleting opens a "Delete legacy key?" confirmation; the key stops working immediately. You cannot create new v1 keys; new keys are always v2.

How to create an API key

1. Go to Settings > API.

2. In the API keys block, click "New API key".

3. Enter a descriptive Label.

4. Choose the access level. Pick "Full access" for admin, or "Only select permissions..." and check just the scopes the key needs.

5. Click "Create".

6. Copy the secret from the "Save your key" screen (it is also copied to your clipboard automatically) and store it securely. Close the dialog.

How to set up a webhook

1. Go to Settings > API.

2. In the Webhooks block, click "New webhook".

3. Enter a Label and the destination URL.

4. Select the resources you want to receive events for, or use "All".

5. Click "Create".

6. Copy the signing secret and store it. Use it to verify the HMAC-SHA256 signature on every incoming request.

7. Click "Done".

8. To confirm delivery, open the webhook's detail page and watch the Recent deliveries list after triggering an event.

Notes

• API key secrets and webhook signing secrets are shown in full only once. Store them securely; if lost, revoke and recreate the key, or rotate the webhook secret.

• Revoking a key, deleting a webhook, deleting a legacy key, or rotating a signing secret all take effect immediately and break anything still using the old value.

• Webhook edits use an explicit "Save webhook" button. Key creation, revocation, and webhook enable/disable/delete apply as soon as you confirm.

• The webhook picker intentionally exposes resource-level patterns rather than per-action event types; the exact action is in each payload's type field.

• Rate limits and full endpoint references live in the public API documentation reachable from the "How it works" button, not in this settings page. The API analytics charts show your actual usage and error rates.

• The public API has two versions: v2 is current (keys prefixed pl_v2_), and v1 is deprecated with a sunset date of November 20, 2026. Migrate v1 integrations to v2 by creating a new key and updating your integration.