Your first request

You have a key. By the end of this page you will have used it, seen exactly what it is allowed to do, and made a write that you can find again.

1. Choose an environment

This page shows the copy-paste setup for the current docs hostname: production on docs.meshi.io, and staging on docs.staging.meshi.io.

export MESHI_BASE="https://api.meshi.io/api/v0/partner"
export MESHI_KEY="<MESHI_PARTNER_PRODUCTION_KEY>"

export MESHI_BASE="https://api.staging.meshi.io/api/v0/partner"
export MESHI_KEY="<MESHI_PARTNER_STAGING_KEY>"

Staging and production keys are provisioned separately. A staging key should be used only with the staging base URL, and a production key only with production.

2. Confirm the key works

Call GET /auth before any write. It confirms that your key resolves to a service account and shows its environment, capabilities, scopes, and any assigned event boundary.

curl -sS "$MESHI_BASE/auth" \
  -H "Authorization: Bearer $MESHI_KEY"

Example response:

{
  "org_id": "<ORG_ID>",
  "principal_type": "service_account",
  "service_account_user_id": "<SERVICE_ACCOUNT_USER_ID>",
  "scopes": ["partner:read", "partner:write"],
  "environment": "production",
  "event_id": "summit-2026",
  "capabilities": {
    "events_read": true,
    "attendees_import": true,
    "attendees_delete": true,
    "attendees_side_retag": true,
    "people_search": true
  },
  "correlation_id": "<CORRELATION_ID>"
}

If scopes does not include partner:write, the key can read but cannot create events, import attendees, trigger enrichment, or trigger matching.

event_id is present when a key is assigned to one event. Treat it as the resource boundary even when a capability is enabled. Such a key can work with that event, its runs, reviews associated with its attendees or held imports, and in-event ID mappings. Requests for another event return 404 EVENT_NOT_FOUND; event creation, generic run creation, org-wide people search, review merges, and other org-wide writes return 403 EVENT_SCOPE_FORBIDDEN. Skip event creation below when the assigned event is already provisioned.

3. Know what your key can do

Scopes are enforced by HTTP method:

Read-only methods can be satisfied by either partner:read or partner:write. Write methods require partner:write.

4. Send a correlation ID

You can send x-correlation-id on any request to thread your own trace ID through the response:

curl -sS "$MESHI_BASE/auth" \
  -H "Authorization: Bearer $MESHI_KEY" \
  -H "x-correlation-id: partner-trace-001"

Meshi echoes the effective ID in the x-correlation-id response header and in every JSON response body. Always log it with integration errors.

5. Make your first write

For an org-scoped key, create an event with an ID from your own system. An event-scoped key must use its assigned event instead.

curl -sS -X POST "$MESHI_BASE/events" \
  -H "Authorization: Bearer $MESHI_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "summit-2026",
    "title": "Annual Partner Summit 2026",
    "description": "Two-day leadership summit",
    "start_date": "2026-09-10",
    "end_date": "2026-09-11",
    "timezone": "America/New_York",
    "visibility": "private",
    "url_slug": "summit-2026"
  }'

201 Created returns the event. If the event ID already exists in your org, the response is 409 PARTNER_ID_CONFLICT; treat that as an already-provisioned event and fetch it before continuing.

6. Where to go next

Follow the Canonical flow to add attendees, poll imports, enrich, match, and read results.