API Reference

Authentication

The Pineprompt REST API authenticates every request with an API key. Each key is bound to a single organization and carries a set of abilities that limit what it may do.

API keys

You may issue a key from the dashboard at Settings → API keys. Every key is scoped to:

  • A single organization (the key's "tokenable").
  • A set of abilities, the granular scopes that limit what the key may do.

The key's value is shown once, at creation, so you should store it somewhere safe; Pineprompt keeps only a hash. Once you have a key, you should send it on every request via the Authorization header:

Authorization: Bearer 3|ppt_live_a1B2c3D4e5F6g7H8i9J0...

Of course, a key already implies its own organization, so no extra header is needed to identify which organization to act in.

Project-scoped endpoints

Every monitor, prompt, brand, and source endpoint requires you to identify the active project:

Pineprompt-Project-Id: 42

Without the header, Pineprompt will respond with 400 Missing required header Pineprompt-Project-Id. If the project does exist but does not belong to the active organization, Pineprompt will respond with 404 Project not found.

Abilities

Every key carries a set of abilities, sometimes called scopes. Abilities mirror the in-app permission model and are enforced by the ability:<name> middleware on every endpoint.

A key may only carry data abilities, listed below at read and write granularity. The governance permissions (managing members, managing billing, and deleting the organization) belong to a member's role rather than to a key, so they are exercised by a person signed in to the dashboard, never by a machine credential.

Field Type Description
organization:read ability

Read the active organization.
organization:manage ability

Update the active organization.
projects:read ability

List and read projects.
projects:write ability

Create, update, and delete projects.
monitors:read ability

List and read monitors.
monitors:write ability

Create, update, and delete monitors.
prompts:read ability

List and read prompts.
prompts:write ability

Create, update, and delete prompts, and manage prompt-tag attachments.
brands:read ability

List brands and read brand mentions.
brands:write ability

Reclassify brands and manage brand-segment attachments.
tags:read ability

List and read tags.
tags:write ability

Create, update, and delete tags.
segments:read ability

List and read segments.
segments:write ability

Create, update, and delete segments.
sources:read ability

List and read sources.
responses:read ability

List and read responses.
citations:read ability

List and read citations.
analytics:read ability

Read analytics endpoints.

Verifying your setup

Before wiring up an integration, you may wish to use GET /api/v1/me as a smoke test. The endpoint returns the key, the active organization, the abilities currently in effect, and the projects you may act in. This is everything you need to confirm that your client is configured correctly.