Me - Devotel Orbit Documentation

{
  "data": {
    "rules": [
      {
        "match_kind": "pstn",
        "match_value": "+442071234567",
        "pattern": "vip",
        "label": "Front desk"
      },
      {
        "match_kind": "prefix",
        "match_value": "+1800",
        "pattern": "priority",
        "label": "Toll-free callers"
      }
    ],
    "patterns": [
      { "id": "standard", "label": "Standard ring", "alertInfo": null, "priority": false },
      { "id": "priority", "label": "Priority alert", "alertInfo": "info=alert-priority", "priority": true },
      { "id": "urgent", "label": "Urgent alert", "alertInfo": "info=alert-urgent", "priority": true },
      { "id": "vip", "label": "VIP ring", "alertInfo": "info=alert-vip", "priority": true },
      { "id": "internal", "label": "Internal ring", "alertInfo": "info=alert-internal", "priority": false },
      { "id": "external", "label": "External ring", "alertInfo": "info=alert-external", "priority": false }
    ]
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

{
  "data": {
    "rules": [
      {
        "match_kind": "pstn",
        "match_value": "+442071234567",
        "pattern": "vip",
        "label": "Front desk"
      },
      {
        "match_kind": "prefix",
        "match_value": "+1800",
        "pattern": "priority",
        "label": "Toll-free callers"
      }
    ],
    "patterns": [
      { "id": "standard", "label": "Standard ring", "alertInfo": null, "priority": false },
      { "id": "priority", "label": "Priority alert", "alertInfo": "info=alert-priority", "priority": true },
      { "id": "urgent", "label": "Urgent alert", "alertInfo": "info=alert-urgent", "priority": true },
      { "id": "vip", "label": "VIP ring", "alertInfo": "info=alert-vip", "priority": true },
      { "id": "internal", "label": "Internal ring", "alertInfo": "info=alert-internal", "priority": false },
      { "id": "external", "label": "External ring", "alertInfo": "info=alert-external", "priority": false }
    ]
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

Working with this group

Every operation under /me reads or writes only the authenticated caller’s own resources: profile preferences, speed-dial favorites, saved campaign drafts, report history, recommendation drafts, and ring rules. The credential on the request determines the tenant: an API key (dv_live_sk_* or dv_test_sk_*) resolves to the organization that owns the key, while a dashboard session resolves to the organization the signed-in user is currently working in.

First call: the identity probe

GET /api/v1/me is the first call every SDK quick start makes: it proves the credential works and returns the identity, organization id, and plan that every later request acts under. Authorization is role-based, so the response carries the caller’s role on the user object and per organization; there is no per-call scope list to request.

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/me" \
  -H "X-API-Key: dv_live_sk_your_key_here"

200

{
  "data": {
    "user": {
      "id": "user_01J9VKD3Q8N2XW7R4T6YB5E0M1",
      "email": "ada@example.com",
      "name": "Ada Okafor",
      "image": null,
      "role": "admin",
      "emailVerified": true,
      "twoFactorEnabled": true,
      "softphone_layout": "compact_bottom_bar",
      "voicemail_to_email_enabled": false,
      "voicemail_to_email_address": null,
      "inbox_signature": "Ada Okafor\nExample Coffee Roasters",
      "inbox_show_archived_tags": false
    },
    "tenant": {
      "id": "org_01J9Z2H4K5P8Q1S3T6V9W2X4Y7",
      "name": "Example Coffee Roasters",
      "slug": "example-coffee",
      "plan": "growth",
      "logoUrl": null
    },
    "organizations": [
      {
        "id": "org_01J9Z2H4K5P8Q1S3T6V9W2X4Y7",
        "name": "Example Coffee Roasters",
        "slug": "example-coffee",
        "logoUrl": null,
        "role": "admin"
      }
    ]
  },
  "meta": {
    "request_id": "req_01HZQX9T2K8V5N3J6D1M4A7B0C",
    "timestamp": "2026-10-15T09:12:44.000Z"
  }
}

List saved campaign drafts from any SDK

GET /api/v1/me/campaign-drafts returns the caller’s saved AI campaign drafts in data.drafts. The history is capped at 50 drafts, so the full list arrives in one response and there is no cursor to follow; meta carries the correlation fields only. The same call in four styles:

curl -X GET "https://api.orbit.devotel.io/api/v1/me/campaign-drafts" \
  -H "X-API-Key: dv_live_sk_your_key_here"

import { Orbit } from '@devotel-orbit/node'

const orbit = new Orbit({
  apiKey: process.env.ORBIT_API_KEY!,
})

const res = await orbit.request('GET', '/me/campaign-drafts')
console.log(res.data.drafts)

import os
from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

res = client.request("GET", "/me/campaign-drafts")
print(res["data"]["drafts"])

package main

import (
	"fmt"
	"io"
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/me/campaign-drafts", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)
	fmt.Println(string(body))
}

200

{
  "data": {
    "drafts": [
      {
        "id": "draft_7f3a91c2e4b0",
        "name": "Spring re-engagement",
        "brief": "Win back customers inactive for 90 days with a 15% comeback offer.",
        "draft": {
          "headline": "We miss you — here's 15% off your next order",
          "sms": "Example Co.: your 15% comeback offer is ready. Reply STOP to opt out.",
          "email": "Hi {{first_name}}, it's been a while — enjoy 15% off this week."
        },
        "channels": ["sms", "email"],
        "createdAt": 1791936000000,
        "updatedAt": 1792022400000
      }
    ]
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

Correlating a request

Every response on this page repeats meta.request_id, a server-generated id for exactly one request. Quote it when reporting a failed call or reading your request logs: support and diagnostics resolve it to the same request across services. meta.timestamp is the server time the response was produced.

title: “Worked identity and org-context samples” description: “The startup introspection chain — call GET /me, read identity + tenant + memberships, decide on the caller’s role — plus a worked sweep of the per-user me/* resources (ring rules, favorites, campaign drafts, generated reports) and the authentication failures this probe surfaces first.”

Worked identity and org-context samples

Bootstrap the session, then decide: call GET /api/v1/me at startup before touching any resource operation, read data.user, data.tenant, and data.organizations out of the same envelope, and branch on the caller’s role before you call a write path. Every signed-in client resolves identity through this probe — the dashboard’s org picker and the mobile client both bootstrap from it. Cache the response per session, keep meta.request_id for support correlation, and re-fetch only on org switch or role change.

Worked sequence: dashboard-adjacent operator reads

The me/* GETs below are the per-user state the dashboard piles onto the post-login bootstrap: distinctive-ring rules, speed-dial favorites, saved AI campaign drafts, and generated-report history. Chain them in this order so a mobile or API client can render the operator’s own resources in one sweep; a drafted campaign row travels as one entry of data.drafts[] with the brief, the generated copy, and the target channels.

// 1. Ring rules — distinctive ringing on inbound callers.
const ring = await fetch("https://api.orbit.devotel.io/api/v1/me/ring-rules", {
  headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
}).then((r) => r.json());
// ring.data.rules → the caller's rules; ring.data.patterns → picker catalog.

// 2. Favorites — one-tap dial targets on the dialpad.
const favorites = await fetch(
  "https://api.orbit.devotel.io/api/v1/me/favorites",
  { headers: { "X-API-Key": process.env.ORBIT_API_KEY! } },
).then((r) => r.json());
// favorites.data.favorites → ordered one-tap targets.

// 3. Campaign drafts — the AI Studio draft history.
const drafts = await fetch(
  "https://api.orbit.devotel.io/api/v1/me/campaign-drafts",
  { headers: { "X-API-Key": process.env.ORBIT_API_KEY! } },
).then((r) => r.json());
// drafts.data.drafts → one entry per saved draft ({ id, name, brief, draft, channels }).

// 4. Generated reports — the Insights → Reports run history (metadata only).
const reports = await fetch(
  "https://api.orbit.devotel.io/api/v1/me/generated-reports",
  { headers: { "X-API-Key": process.env.ORBIT_API_KEY! } },
).then((r) => r.json());
// reports.data.reports → metadata rows; row-level content stays client-side.

A drafted campaign row — one entry of data.drafts[] from the third call above (the generated blueprint is null when the row was saved brief-only):

{
  "id": "draft_8b0d2f4a6c8e0b2d4f6a",
  "name": "Q4 re-engagement — lapsed SMS",
  "brief": "Win back lapsed SMS customers with a 10% offer before holiday spend starts",
  "draft": {
    "sms_headline": "Come back for 10% off",
    "sms_body": "We miss you — 10% off your next order, ends Saturday."
  },
  "channels": ["sms"],
  "createdAt": 1755860400125,
  "updatedAt": 1755860400125
}

Each sweep is scoped to the signed-in operator only — a leaked row id from another user never resolves. Empty state is an empty array (or data.draft: null on the Recommendations tester), so render your empty-view CTA rather than a table skeleton.

Worked reads — ring rules and favorites

Each per-user read below is the second leg of the worked sequence: the GET the bootstrap chain fires, paired with the envelope it answers. Chain them after GET /me resolves the caller.

Ring rules — the caller’s distinctive-ring rules

GET /api/v1/me/ring-rules

Distinctive-ring rules map an inbound-caller match to the ring pattern the softphone plays; data.patterns is the picker catalog the dashboard renders for the rule editor. Request

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/me/ring-rules" \
  -H "X-API-Key: $ORBIT_API_KEY"

Node.js

const res = await fetch("https://api.orbit.devotel.io/api/v1/me/ring-rules", {
  headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
});
console.log(await res.json());

Response

{
  "data": {
    "rules": [
      {
        "match_kind": "pstn",
        "match_value": "+442071234567",
        "pattern": "vip",
        "label": "Front desk"
      },
      {
        "match_kind": "prefix",
        "match_value": "+1800",
        "pattern": "priority",
        "label": "Toll-free callers"
      }
    ],
    "patterns": [
      { "id": "standard", "label": "Standard ring", "alertInfo": null, "priority": false },
      { "id": "priority", "label": "Priority alert", "alertInfo": "info=alert-priority", "priority": true },
      { "id": "urgent", "label": "Urgent alert", "alertInfo": "info=alert-urgent", "priority": true },
      { "id": "vip", "label": "VIP ring", "alertInfo": "info=alert-vip", "priority": true },
      { "id": "internal", "label": "Internal ring", "alertInfo": "info=alert-internal", "priority": false },
      { "id": "external", "label": "External ring", "alertInfo": "info=alert-external", "priority": false }
    ]
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

Favorites — one-tap dial targets

GET /api/v1/me/favorites

Speed-dial favorites ordered by sort_order then creation time — the dialpad’s one-tap call surface. label is null when the caller never named the target. Request

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/me/favorites" \
  -H "X-API-Key: $ORBIT_API_KEY"

Node.js

const res = await fetch("https://api.orbit.devotel.io/api/v1/me/favorites", {
  headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
});
console.log(await res.json());

Response

{
  "data": {
    "favorites": [
      {
        "id": "favorite_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3",
        "target_kind": "pstn",
        "target_value": "+14155552671",
        "label": "Front desk",
        "sort_order": 0,
        "created_at": "2026-08-26T10:00:00.000Z"
      },
      {
        "id": "favorite_3a9e4c2b1d8f4a6e9c7b5d2e4f6a8c1",
        "target_kind": "sip",
        "target_value": "sip:support@pbx.example.com",
        "label": null,
        "sort_order": 10,
        "created_at": "2026-08-26T10:05:00.000Z"
      }
    ]
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

Campaign drafts — the AI Studio draft history

GET /api/v1/me/campaign-drafts

One entry per saved AI Studio draft; draft is null when the row was saved brief-only, so gate the preview panel on its presence. Request

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/me/campaign-drafts" \
  -H "X-API-Key: $ORBIT_API_KEY"

Node.js

const res = await fetch("https://api.orbit.devotel.io/api/v1/me/campaign-drafts", {
  headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
});
console.log(await res.json());

Response

{
  "data": {
    "drafts": [
      {
        "id": "draft_8b0d2f4a6c8e0b2d4f6a",
        "name": "Q4 re-engagement — lapsed SMS",
        "brief": "Win back lapsed SMS customers with a 10% offer before holiday spend starts",
        "draft": {
          "sms_headline": "Come back for 10% off",
          "sms_body": "We miss you — 10% off your next order, ends Saturday."
        },
        "channels": ["sms"],
        "createdAt": 1755860400125,
        "updatedAt": 1755860400125
      }
    ]
  },
  "meta": {
    "request_id": "req_01HZQX4E7JQ4M2E2H2DM9XE5FJ",
    "timestamp": "2026-08-26T12:00:00.000Z"
  }
}

Read the authenticated caller

GET /api/v1/me

Returns the caller’s identity, the active tenant, and every organization the caller belongs to in one envelope. Request

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/me" \
  -H "X-API-Key: $ORBIT_API_KEY"

Node.js

const res = await fetch("https://api.orbit.devotel.io/api/v1/me", {
  headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
});
console.log(await res.json());

Response

{
  "data": {
    "user": {
      "id": "usr_9f2a4c6e1b7d3e8f5012a4b6c8d0e2f4",
      "email": "jane@acme.example",
      "name": "Jane Cooper",
      "image": null,
      "role": "admin",
      "emailVerified": true,
      "twoFactorEnabled": false,
      "softphone_layout": "compact_bottom_bar",
      "voicemail_to_email_enabled": false,
      "voicemail_to_email_address": null,
      "inbox_signature": null,
      "inbox_show_archived_tags": false
    },
    "tenant": {
      "id": "ten_4c8d1e6a9b2f4d8c0e2a4c6e8b0d2f4a",
      "name": "Acme Logistics",
      "slug": "acme-logistics",
      "plan": "scale",
      "logoUrl": null
    },
    "organizations": [
      {
        "id": "org_2b6c8e0a4d6f8b0c2e4a6c8d0e2f4a6c",
        "name": "Acme Logistics",
        "slug": "acme-logistics",
        "logoUrl": null,
        "role": "admin"
      },
      {
        "id": "org_7d0e2a4c6e8b0d2f4a6c8e0a2c4e6a8b",
        "name": "Acme Retail",
        "slug": "acme-retail",
        "logoUrl": "https://cdn.orbit.devotel.io/org-logos/acme-retail.png",
        "role": "member"
      }
    ]
  },
  "meta": {
    "request_id": "req_me_bootstrap_01",
    "timestamp": "2026-09-11T08:12:44.310Z"
  }
}

The three data keys always arrive together: user carries the identity fields above plus the caller’s per-user preferences (softphone layout, voicemail-to-email opt-in, inbox signature), tenant is the organization context every subsequent request runs in, and organizations lists every membership with the caller’s role in each.

Preflight: decide on the caller’s role

Branch on data.user.role / membership role before calling a write path

The identity probe answers three startup questions in one call: who is calling (data.user), which organization the key is bound to (data.tenant.slug), and whether the caller’s role in that org justifies the call you are about to make (data.organizations[].role). A workspace-scoped key resolves to exactly one tenant; multi-org dashboard (Clerk-session) callers receive every membership in data.organizations. An admin-of-one-org membership appears alongside the rest — treat the per-org role as the decision input and the org-scoped endpoint’s own verdict as authoritative.

const res = await fetch("https://api.orbit.devotel.io/api/v1/me", {
  headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
});
const { data } = await res.json();

// Branch on the caller's role before any write path.
const membership = data.organizations.find((o) => o.slug === data.tenant.slug);
const role = membership?.role ?? "member";
if (role !== "admin" && role !== "owner") {
  console.warn(`Role "${role}" cannot manage this resource — expect 403 on write paths`);
}

import os, requests

r = requests.get(
    "https://api.orbit.devotel.io/api/v1/me",
    headers={"X-API-Key": os.environ["ORBIT_API_KEY"]},
)
data = r.json()["data"]

# Branch on the caller's role before any write path.
membership = next(
    (o for o in data["organizations"] if o["slug"] == data["tenant"]["slug"]),
    None,
)
role = membership["role"] if membership else "member"
if role not in ("admin", "owner"):
    print(f'Role "{role}" cannot manage this resource — expect 403 on write paths')

using System.Net.Http.Json;

using var http = new HttpClient();
http.DefaultRequestHeaders.Add("X-API-Key", Environment.GetEnvironmentVariable("ORBIT_API_KEY"));
var me = await http.GetFromJsonAsync<JsonElement>("https://api.orbit.devotel.io/api/v1/me");
var data = me.GetProperty("data");

// Branch on the caller's role before any write path.
var role = data.GetProperty("user").GetProperty("role").GetString() ?? "member";
if (role is not ("admin" or "owner"))
{
    Console.WriteLine($"Role \"{role}\" cannot manage this resource — expect 403 on write paths");
}

The decision table for the role you read:

Caller state	`GET /me`	Role-less write that follows
Credential valid; role carries the write path’s grant	`200` — full envelope	`200` / `201` — operation succeeds
Credential valid; role lacks the grant	`200` — full envelope	`403 FORBIDDEN` — surface, rotating retry never heals
Credential missing or invalid	`401` — see below	no downstream call is reached

A 200 on /me tells you the credential is good — it never tells you a write will succeed. Read the role, decide, and treat the operation’s own 403 as the authoritative verdict when the table disagrees with your role map.

Org-context and capability probes in the me surface

The me surface resolves the caller’s active organization context and capability footprint. Use these probes to hide unsupported actions, decide whether an organization area should surface in the dashboard, and map each caller to the operations they can drive. The GET /me envelope is the org-context probe: it resolves the active tenant and memberships in one round trip. Request

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/me" \
  -H "X-API-Key: $ORBIT_API_KEY"

Node.js

const res = await fetch("https://api.orbit.devotel.io/api/v1/me", {
  headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
});
const { data } = await res.json();
console.log(data.tenant, data.organizations);

Response

{
  "data": {
    "tenant": {
      "id": "ten_4c8d1e6a9b2f4d8c0e2a4c6e8b0d2f4a",
      "name": "Acme Logistics",
      "slug": "acme-logistics",
      "plan": "scale",
      "logoUrl": null
    },
    "organizations": [
      {
        "id": "org_2b6c8e0a4d6f8b0c2e4a6c8d0e2f4a6c",
        "name": "Acme Logistics",
        "slug": "acme-logistics",
        "role": "admin"
      }
    ]
  }
}

The data.tenant block carries the active organization footprint (id, name, slug, plan) every subsequent request runs against; data.organizations lists every membership with the caller’s role. Prefer this single envelope over a second call — there is no separate GET /me/org or GET /me/memberships path; the memberships guard lives on this envelope.

Membership / role guard

Resolve the caller’s membership in the active organization before any write path and gate on its role — the same guard the dashboard applies when opening an organization area.

ROLE=$(curl -s -X GET "https://api.orbit.devotel.io/api/v1/me" \
  -H "X-API-Key: $ORBIT_API_KEY" \
  | jq -r '.data.organizations[] | select(.slug == "acme-logistics") | .role')
echo "caller role: $ROLE"

const res = await fetch("https://api.orbit.devotel.io/api/v1/me", {
  headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
});
const { data } = await res.json();

const membership = data.organizations.find(
  (o: { slug: string; role: string }) => o.slug === data.tenant.slug,
);
const role = membership?.role ?? "member";
console.log(`caller role: ${role}`);

The guard answers “does this caller belong to the active org, and with what role” without a dedicated memberships call. Membership role is the only role input the me surface honors — org-scoped endpoints refuse operations the role does not carry.

Feature-gate probe — predictive activation schedule

GET /api/v1/me/predictive-activation-schedule

GET /api/v1/me/predictive-activation-schedule is the capability probe for the predictive-models panel: it returns the caller’s per-model auto-activation schedule intent, or data.schedule: null when no schedule is saved. SDK helpers use null to hide the panel and non-null to render it, so the probe doubles as the feature gate. Request

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/me/predictive-activation-schedule" \
  -H "X-API-Key: $ORBIT_API_KEY"

Node.js

const res = await fetch(
  "https://api.orbit.devotel.io/api/v1/me/predictive-activation-schedule",
  { headers: { "X-API-Key": process.env.ORBIT_API_KEY! } },
);
const { data } = await res.json();
const scheduleEnabled = data.schedule !== null;
console.log("predictive schedule saved:", scheduleEnabled);

Response with a saved schedule

{
  "data": {
    "schedule": {
      "churn_propensity": {
        "enabled": true,
        "cadence": "daily",
        "topN": 100,
        "nameTemplate": "Churn – {date}"
      }
    }
  },
  "meta": {}
}

Response with no schedule saved

{
  "data": { "schedule": null },
  "meta": {}
}

Build the features map your SDK helpers consume from the probe: featuresEnabled.predictiveSchedule = data.schedule !== null, and each model key that survives the server registry (churn_propensity, conversion_intent, lifetime_value, engagement_fatigue) marks its panel as enabled. A PUT on the same path toggles the intent — treat the read as the probe and the write as the setter, never cache the write’s response as the gate.

Chain — authenticated caller → memberships → capabilities

The standard bootstrap chain the me surface supports: (1) call GET /me to resolve identity, (2) guard on data.organizations membership for the active organization, and (3) probe GET /me/predictive-activation-schedule so unsupported actions stay hidden.

// 1. Resolve the authenticated caller.
const meRes = await fetch("https://api.orbit.devotel.io/api/v1/me", {
  headers: { "X-API-Key": process.env.ORBIT_API_KEY! },
});
const { data: me } = await meRes.json();

// 2. Guard on membership for the active organization.
const membership = me.organizations.find(
  (o: { slug: string; role: string }) => o.slug === me.tenant.slug,
);
const role = membership?.role ?? "member";

// 3. Probe capabilities before rendering the panel.
const capRes = await fetch(
  "https://api.orbit.devotel.io/api/v1/me/predictive-activation-schedule",
  { headers: { "X-API-Key": process.env.ORBIT_API_KEY! } },
);
const { data: cap } = await capRes.json();
const featuresEnabled = { predictiveSchedule: cap.schedule !== null };

console.log({ user: me.user.email, role, featuresEnabled });

Each probe is idempotent, so cache the envelope per session and re-fetch only on org switch or role change. Treat the chain as the only sequence that establishes org context before touching a resource operation.

Errors worth branching on

This probe is where an invalid credential surfaces first — an integration that skips the bootstrap re-discovers the same 401 on every later call. The mechanics of the envelope (error.code / message / status / details, the meta.docs_url trail) are owned by the error handling guide; only the /me-specific branch is hers.

401 — the credential itself fails

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "The API key is missing, invalid, or has been revoked.",
    "status": 401
  },
  "meta": {
    "request_id": "req_me_auth_01",
    "timestamp": "2026-09-11T08:12:45.120Z",
    "docs_url": "https://docs.orbit.devotel.io/errors/INVALID_API_KEY"
  }
}

A 401 on this probe means the X-API-Key header value itself fails — it never means the identity payload moved. The failure precedes tenant resolution, so there is no data envelope to fall back to. Read meta.docs_url for the code’s remedy anchor; rotate the key or mint a new one, because retrying the same header re-fails identically.

Retry matrix

Class	Meaning	Branch response
401 `INVALID_API_KEY`	the credential itself is missing, invalid, or revoked	Surface. Rotate or mint a key; retrying the same value re-fails identically. Follow `meta.docs_url` to the code’s remedy.
403 `FORBIDDEN`	the credential is valid but the caller’s role lacks the operation’s grant	Surface on the operation, not here. `/me` itself returns `200`; the write path you preflighted against the role table answers `403`. Fix the role or the scope — a retry with the same credential never heals it.
429 `RATE_LIMITED`	the window quota is exhausted	Retry after `error.details.retry_after` (or the `Retry-After` header) with the same request. Cache the `200` payload per session so a retry storm is unnecessary.
5xx transient	a backing lookup failed	Retry with backoff. The startup probe is idempotent; serve your last cached envelope while you retry rather than failing the session.

The platform-wide retry-vs-terminal decision table lives in the error handling guide.

Worked response reference — every operation on this page

The sections above teach the bootstrap chain; this reference supplies the populated response body for every remaining operation on the page. Every /me read returns only the authenticated caller’s own resources: drafts, reports, favorites, and ring rules are stored per user, and a row id leaked from another user never resolves here. The API key on X-API-Key determines the tenant, so every body below is already scoped to one organization.

The identity probe — org id, plan, user id, roles

GET /api/v1/me is the first call in the SDK quick start: one round trip that proves the key works and returns the org id (data.tenant.id), the plan (data.tenant.plan), the user id (data.user.id), the workspace role (data.user.role), and the caller’s per-organization roles (data.organizations[].role). There is no scopes array on a key: the key binds to one tenant, and authorization rides on those roles, which is exactly what the preflight above branches on.

GET /api/v1/me

Request

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/me" \
  -H "X-API-Key: $ORBIT_API_KEY"

Response

{
  "data": {
    "user": {
      "id": "usr_9f2a4c6e1b7d3e8f5012a4b6c8d0e2f4",
      "email": "jane@acme.example",
      "name": "Jane Cooper",
      "image": null,
      "role": "admin",
      "emailVerified": true,
      "twoFactorEnabled": false,
      "softphone_layout": "compact_bottom_bar",
      "voicemail_to_email_enabled": false,
      "voicemail_to_email_address": null,
      "inbox_signature": null,
      "inbox_show_archived_tags": false
    },
    "tenant": {
      "id": "ten_4c8d1e6a9b2f4d8c0e2a4c6e8b0d2f4a",
      "name": "Acme Logistics",
      "slug": "acme-logistics",
      "plan": "scale",
      "logoUrl": null
    },
    "organizations": [
      {
        "id": "org_2b6c8e0a4d6f8b0c2e4a6c8d0e2f4a6c",
        "name": "Acme Logistics",
        "slug": "acme-logistics",
        "logoUrl": null,
        "role": "admin"
      },
      {
        "id": "org_7d0e2a4c6e8b0d2f4a6c8e0a2c4e6a8b",
        "name": "Acme Retail",
        "slug": "acme-retail",
        "logoUrl": null,
        "role": "member"
      }
    ]
  },
  "meta": {
    "request_id": "req_01K4ME1DPR0BE000000000000001",
    "timestamp": "2026-10-15T09:00:00.000Z"
  }
}

Campaign drafts — list and replace

GET /api/v1/me/campaign-drafts

The AI Studio draft history, stored per caller. data.drafts is the list the draft picker renders; draft is null for brief-only rows, so gate any preview panel on its presence. Request — the same call in cURL, the typed Node SDK’s escape hatch, Python, and Go:

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/me/campaign-drafts" \
  -H "X-API-Key: $ORBIT_API_KEY"

Node.js

import { Orbit } from "@devotel-orbit/node";

const orbit = new Orbit({ apiKey: process.env.ORBIT_API_KEY! });

const res = await orbit.request("GET", "/me/campaign-drafts");
console.log(res.data.drafts);

Python

from orbit_sdk import OrbitClient

client = OrbitClient.from_env()  # reads ORBIT_API_KEY

res = client.request("GET", "/me/campaign-drafts")
print(res["data"]["drafts"])

package main

import (
	"net/http"
	"os"
)

func main() {
	req, _ := http.NewRequest("GET", "https://api.orbit.devotel.io/api/v1/me/campaign-drafts", nil)
	req.Header.Set("X-API-Key", os.Getenv("ORBIT_API_KEY"))

	res, _ := http.DefaultClient.Do(req)
	defer res.Body.Close()
	// res.Body → { "data": { "drafts": [...] }, "meta": { ... } }
}

Response

{
  "data": {
    "drafts": [
      {
        "id": "draft_8b0d2f4a6c8e0b2d4f6a",
        "name": "Q4 re-engagement — lapsed SMS",
        "brief": "Win back lapsed SMS customers with a 10% offer before holiday spend starts",
        "draft": {
          "sms_headline": "Come back for 10% off",
          "sms_body": "We miss you — 10% off your next order, ends Saturday."
        },
        "channels": ["sms"],
        "createdAt": 1755860400125,
        "updatedAt": 1755860400125
      },
      {
        "id": "draft_1c3e5a7b9d0f2e4a6c8b",
        "name": "Holiday VIP early access",
        "brief": "Give VIP contacts 48h early access to the holiday sale",
        "draft": null,
        "channels": ["sms", "email"],
        "createdAt": 1756119600000,
        "updatedAt": 1756119600000
      }
    ]
  },
  "meta": {
    "request_id": "req_01K4MEDRAFTSL1ST000000000001",
    "timestamp": "2026-10-15T09:00:01.000Z"
  }
}

The list is bounded and replaced whole on write; PUT re-validates every row and answers the same rows back:

PUT /api/v1/me/campaign-drafts

{
  "data": {
    "updated": true,
    "drafts": [
      {
        "id": "draft_8b0d2f4a6c8e0b2d4f6a",
        "name": "Q4 re-engagement — lapsed SMS",
        "brief": "Win back lapsed SMS customers with a 10% offer before holiday spend starts",
        "draft": {
          "sms_headline": "Come back for 10% off",
          "sms_body": "We miss you — 10% off your next order, ends Saturday."
        },
        "channels": ["sms"],
        "createdAt": 1755860400125,
        "updatedAt": 1760518800000
      }
    ]
  },
  "meta": {
    "request_id": "req_01K4MEDRAFTSREPL000000000001",
    "timestamp": "2026-10-15T09:00:02.000Z"
  }
}

Generated reports — the Insights run history

GET /api/v1/me/generated-reports

Metadata for the caller’s generated reports, most recent first. Row-level report content is never persisted server-side, so each entry carries the column layout the report grid renders, not the rows themselves. Request

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/me/generated-reports" \
  -H "X-API-Key: $ORBIT_API_KEY"

Response

{
  "data": {
    "reports": [
      {
        "id": "rep_5e7a9c1b3d2f4a6e8c0b",
        "name": "September campaign ROI",
        "type": "campaign_roi",
        "generatedAt": "2026-10-01T07:42:00.000Z",
        "columns": [
          { "key": "campaign", "label": "Campaign" },
          { "key": "spend", "label": "Spend" },
          { "key": "roi", "label": "ROI" }
        ]
      }
    ]
  },
  "meta": {
    "request_id": "req_01K4MEREPORTSL1ST000000001",
    "timestamp": "2026-10-15T09:00:03.000Z"
  }
}

PUT replaces the caller’s history with the sanitized list and echoes it back:

PUT /api/v1/me/generated-reports

{
  "data": {
    "updated": true,
    "reports": [
      {
        "id": "rep_5e7a9c1b3d2f4a6e8c0b",
        "name": "September campaign ROI",
        "type": "campaign_roi",
        "generatedAt": "2026-10-01T07:42:00.000Z",
        "columns": [
          { "key": "campaign", "label": "Campaign" },
          { "key": "spend", "label": "Spend" },
          { "key": "roi", "label": "ROI" }
        ]
      }
    ]
  },
  "meta": {
    "request_id": "req_01K4MEREPORTSREPL000000001",
    "timestamp": "2026-10-15T09:00:04.000Z"
  }
}

Recommendations draft — the tester’s saved inputs

GET /api/v1/me/recommendations-draft

The Recommendations tester’s editable input set: product catalog, observed signals, and scoring weights. data.draft is null until the caller saves a first configuration, so seed your defaults on null. Request

cURL

curl -X GET "https://api.orbit.devotel.io/api/v1/me/recommendations-draft" \
  -H "X-API-Key: $ORBIT_API_KEY"

Response

{
  "data": {
    "draft": {
      "catalog": [
        {
          "product_id": "prod_2201",
          "title": "Trail running shoes",
          "category": "footwear",
          "brand": "Cascade",
          "price": 129.5,
          "tags": "trail,sale",
          "in_stock": true
        }
      ],
      "signals": [
        {
          "type": "view",
          "category": "footwear",
          "brand": "Cascade",
          "product_id": "prod_2201",
          "age_days": 2,
          "value": null
        }
      ],
      "profileId": "prof_8817",
      "limitRaw": "12",
      "halfLifeRaw": "14",
      "suppressPurchased": true,
      "weightsRaw": {
        "category": "medium",
        "brand": "low",
        "tag": "low",
        "price_fit": "high",
        "popularity": "medium"
      }
    }
  },
  "meta": {
    "request_id": "req_01K4MERECODRAFTGET00000001",
    "timestamp": "2026-10-15T09:00:05.000Z"
  }
}

PUT saves the full tester state and answers it back with updated: true:

PUT /api/v1/me/recommendations-draft

{
  "data": {
    "updated": true,
    "draft": {
      "catalog": [
        {
          "product_id": "prod_2201",
          "title": "Trail running shoes",
          "category": "footwear",
          "brand": "Cascade",
          "price": 129.5,
          "tags": "trail,sale",
          "in_stock": true
        }
      ],
      "signals": [
        {
          "type": "view",
          "category": "footwear",
          "brand": "Cascade",
          "product_id": "prod_2201",
          "age_days": 2,
          "value": null
        }
      ],
      "profileId": "prof_8817",
      "limitRaw": "12",
      "halfLifeRaw": "14",
      "suppressPurchased": true,
      "weightsRaw": {
        "category": "medium",
        "brand": "low",
        "tag": "low",
        "price_fit": "high",
        "popularity": "medium"
      }
    }
  },
  "meta": {
    "request_id": "req_01K4MERECODRAFTPUT00000001",
    "timestamp": "2026-10-15T09:00:06.000Z"
  }
}

Ring rules — replace the caller’s rules

PUT /api/v1/me/ring-rules

PUT replaces the caller’s full rules array (validated and deduplicated server-side) and echoes the stored rules back with the same shapes the GET above documents:

{
  "data": {
    "updated": true,
    "rules": [
      {
        "match_kind": "pstn",
        "match_value": "+442071234567",
        "pattern": "vip",
        "label": "Front desk"
      }
    ]
  },
  "meta": {
    "request_id": "req_01K4MERINGRULESREP00000001",
    "timestamp": "2026-10-15T09:00:07.000Z"
  }
}

Favorites — create, relabel, delete

POST /api/v1/me/favorites

A successful pin answers 201 with the created row; the dialpad Favorites tab renders it immediately:

{
  "data": {
    "favorite": {
      "id": "favorite_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3",
      "target_kind": "pstn",
      "target_value": "+14155552671",
      "label": "Front desk",
      "sort_order": 0,
      "created_at": "2026-10-15T09:00:08.000Z"
    }
  },
  "meta": {
    "request_id": "req_01K4MEFAVCREATE000000001",
    "timestamp": "2026-10-15T09:00:08.000Z"
  }
}

PATCH /api/v1/me/favorites/{id}

Relabel or reorder one pin; the answer carries the updated row:

{
  "data": {
    "updated": true,
    "favorite": {
      "id": "favorite_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3",
      "target_kind": "pstn",
      "target_value": "+14155552671",
      "label": "Front desk (day)",
      "sort_order": 1,
      "created_at": "2026-10-15T09:00:08.000Z"
    }
  },
  "meta": {
    "request_id": "req_01K4MEFAVPATCH0000000001",
    "timestamp": "2026-10-15T09:00:09.000Z"
  }
}

DELETE /api/v1/me/favorites/{id}

A delete that belongs to the caller answers deleted: true with the removed id:

{
  "data": {
    "deleted": true,
    "id": "favorite_8fb2d1b7c00c4ec9a1d3f5e7b9c1d3"
  },
  "meta": {
    "request_id": "req_01K4MEFAVDELETE00000001",
    "timestamp": "2026-10-15T09:00:10.000Z"
  }
}

Correlating with support — `meta.request_id`

Every response on this page, 200s and errors alike, carries meta.request_id. Quote that value in a support ticket or a bug report and it resolves to the exact request trace on our side; it is the correlation key between your logs and ours. In sandbox runs (X-Test-Mode: true or a dv_test_sk_* key) the envelope additionally carries meta.test_mode: true, so a pasted body is self-identifying as sandbox traffic.

API Reference

All Endpoints

Me

Working with this group

First call: the identity probe

List saved campaign drafts from any SDK

Correlating a request

Worked identity and org-context samples

Worked sequence: dashboard-adjacent operator reads

Worked reads — ring rules and favorites

Ring rules — the caller’s distinctive-ring rules

Favorites — one-tap dial targets

Campaign drafts — the AI Studio draft history

Read the authenticated caller

Preflight: decide on the caller’s role

Org-context and capability probes in the me surface

Membership / role guard

Feature-gate probe — predictive activation schedule

Chain — authenticated caller → memberships → capabilities

Errors worth branching on

401 — the credential itself fails

Retry matrix

Worked response reference — every operation on this page

The identity probe — org id, plan, user id, roles

Campaign drafts — list and replace

Generated reports — the Insights run history

Recommendations draft — the tester’s saved inputs

Ring rules — replace the caller’s rules

Favorites — create, relabel, delete

Correlating with support — `meta.request_id`

​Working with this group

​First call: the identity probe

​List saved campaign drafts from any SDK

​Correlating a request

​Worked identity and org-context samples

​Worked sequence: dashboard-adjacent operator reads

​Worked reads — ring rules and favorites

​Ring rules — the caller’s distinctive-ring rules

​Favorites — one-tap dial targets

​Campaign drafts — the AI Studio draft history

​Read the authenticated caller

​Preflight: decide on the caller’s role

​Org-context and capability probes in the me surface

​Membership / role guard

​Feature-gate probe — predictive activation schedule

​Chain — authenticated caller → memberships → capabilities

​Errors worth branching on

​401 — the credential itself fails

​Retry matrix

​Worked response reference — every operation on this page

​The identity probe — org id, plan, user id, roles

​Campaign drafts — list and replace

​Generated reports — the Insights run history

​Recommendations draft — the tester’s saved inputs

​Ring rules — replace the caller’s rules

​Favorites — create, relabel, delete

​Correlating with support — meta.request_id

Working with this group

First call: the identity probe

List saved campaign drafts from any SDK

Correlating a request

Worked identity and org-context samples

Worked sequence: dashboard-adjacent operator reads

Worked reads — ring rules and favorites

Ring rules — the caller’s distinctive-ring rules

Favorites — one-tap dial targets

Campaign drafts — the AI Studio draft history

Read the authenticated caller

Preflight: decide on the caller’s role

Org-context and capability probes in the me surface

Membership / role guard

Feature-gate probe — predictive activation schedule

Chain — authenticated caller → memberships → capabilities

Errors worth branching on

401 — the credential itself fails

Retry matrix

Worked response reference — every operation on this page

The identity probe — org id, plan, user id, roles

Campaign drafts — list and replace

Generated reports — the Insights run history

Recommendations draft — the tester’s saved inputs

Ring rules — replace the caller’s rules

Favorites — create, relabel, delete

Correlating with support — `meta.request_id`