No SAGARIS SDK: generate one from the OpenAPI spec
There is no official SAGARIS client library, in any language. We would rather say that plainly than ship a thin wrapper we cannot keep current. What we do publish is a machine-readable description of the whole API, which you can generate a client from, and this page is about the parts of that generated client you will still need to finish yourself.
The OpenAPI document
GET /api/v1/openapi.json returns an OpenAPI 3.1 description of the public API. It needs no authentication, because it is documentation. Point a generator, an API client such as Postman, or a docs viewer at it.
- All nineteen operations, each carrying the single scope it requires, so a generated client can surface a permissions error before you deploy it.
- Fifteen named schemas: the error envelope, two list meta blocks, and the shapes for contacts, activities, deals, sequences, enrollments, suppression and the Social checklist.
- The Idempotency-Key header on the nine write operations that honour it, so a generated client exposes it as a parameter rather than leaving you to add headers by hand.
- The bearer security scheme, so generated clients know to send Authorization rather than a query parameter.
A drift-guard test holds the document's operation list equal to the actual route files, so an endpoint cannot be added, renamed or removed without the document following in the same change. The operations it lists are the operations that exist.
What a generated client will not do for you
Generation gets you types and method signatures. These three things it will get wrong or omit, and all three are worth handling before you go to production.
- Do not trust the error list as complete
- The document declares most refusals per operation, with gaps. Two real refusals are under-declared: a 402 when the workspace is read-only for a billing reason appears only on PUT /contacts/assert and the two Social checklist writes, though six more writes can return it, and a 423 when enrollment is blocked by the workspace outreach pause appears nowhere. Both can happen. The two /linkedin/actions operations also answer 400 and 429 without declaring them. If your generated client models errors as a closed set, add these, or an unexpected 402 will surface as a parsing failure rather than as the billing problem it is.
- Branch on the code, not the status
- 429 means two unrelated things, a throughput limit and a plan cap, and only one of them is worth retrying. Generated clients typically retry on status alone. Read the code field before you retry anything.
- Webhook verification is not in here
- The document describes requests you make to us. Verifying the HMAC signature on deliveries we make to you is not part of the REST surface and no generator will produce it. That code is on the Webhooks page.
One practical note before you pick a tool: this is a 3.1 document, and generator support for 3.1 still lags 3.0 in places. Check that yours reads 3.1 rather than silently degrading.
Calling it without a client at all
The API is small enough that a generated client is genuinely optional. Nineteen operations, one credential, one header, and a response envelope with the same two fields on every path except /linkedin/actions. For most integrations a few functions around your language's HTTP library will be less code than the generated client, and easier to reason about when something is refused.
If the client is an AI agent
If what you are building is an agent rather than an integration, skip the client entirely. SAGARIS serves a Model Context Protocol endpoint at /api/v1/mcp that takes the same API key, so an MCP-capable agent can be pointed at a workspace without any generated code.
Its tool list is derived from the same operations and filtered by the key's scopes. Read tools are the GET operations plus the Brain views. A write operation becomes a tool only when its scope is on one of two short lists fixed in code: the Social checklist submit and record scopes, which submit drafts for a person to approve or record research findings and never publish, and linkedin.execute, which lets a connected agent claim, start and report a LinkedIn action that it performs in its own browser session. Claiming and starting stay refused until LinkedIn execution is activated for the environment.
The scopes that write contacts, deals, activities, enrollment and suppression are on neither list, so none of those operations is a tool: an agent makes them through the REST API, with a key you scoped deliberately. The LinkedIn tool still changes the record through what the agent reports: SAGARIS logs a reported send as an activity, moves the contact's LinkedIn status forward and, for a sequence step, advances the sequence, and a reported accepted connection marks the contact connected.
The endpoint also serves MCP Events, so an agent that can take a webhook, a ChatGPT Dot for example, subscribes to linkedin.work.available, linkedin.schedule.changed and linkedin.reconnect.requested and is woken instead of polling.
Behaviour on this page is read from
- src/lib/public-api/openapi-spec.ts
- src/app/api/v1/openapi.json/route.ts
- src/lib/public-api/openapi-spec.test.ts
- src/lib/billing/api-write-gate.ts
- src/app/api/v1/sequences/enroll/route.ts
- src/lib/mcp/tool-surface.ts
- src/app/api/v1/mcp/route.ts
- src/lib/linkedin/action-api.ts
- src/lib/linkedin/action-store.ts
Was this page helpful?
In this topic