Calling the API
PULSE’s API is gRPC, package pulse.v1, plus the shared runink.ui.*.v1
services. There is no REST or JSON API for business data.
Transports
Everything is on one port.
| Client | How it connects |
|---|---|
| Native gRPC (Go, grpcurl, the Linux and Android app) | HTTP/2 with content-type: application/grpc |
| Browsers | gRPC-Web over the same port |
For browsers served from another origin, the origin must be listed in
CORS_ALLOWED_ORIGINS. The allowed request headers include Authorization,
X-Grpc-Web, grpc-timeout, x-agent-trace-id, x-idempotency-key,
x-pulse-csrf, and x-pulse-session.
Authenticate
Call IdentityService/Login with a username and password. The token is in
accessToken:
TOK=$(grpcurl -plaintext -d '{"username":"admin","password":"<password>"}' \
localhost:52000 pulse.v1.IdentityService/Login | jq -r '.accessToken')Send it on every other call:
grpcurl -plaintext -H "authorization: Bearer $TOK" -d '{}' \
localhost:52000 pulse.v1.CampaignService/ListCampaignsOnly three things work without a token: IdentityService/Login,
ModelService/GetModelStatus, and reflection (when it is turned on).
Refresh a session at POST /auth/refresh. See
HTTP endpoints.
Browsers: the session cookie
A browser has nowhere safe to keep a token — anything the page can store, any
script on the page can read — so the web client never receives one. It asks for
cookie mode by sending x-pulse-session: cookie on Login or on
POST /auth/google. The backend answers with no token in the body and sets the
session as a host-only, HttpOnly, Secure, SameSite=Strict cookie, which
the browser then attaches to every call by itself. Sign out at
POST /auth/logout, which revokes the session and clears the cookie; page
scripts cannot clear it themselves.
Because a cookie travels with any request to the host, whoever wrote the page, a call authenticated by the cookie must prove it came from the PULSE app, in two ways, both required:
- the header
x-pulse-csrf: 1— a cross-site form cannot set a custom header; - an
Originthe server trusts: the server’s own host,PULSE_PUBLIC_BASE_URL, or an exact entry ofCORS_ALLOWED_ORIGINS. A*never counts.
Native clients are unaffected: a bearer header is not sent automatically, so it is not a cross-site risk, and neither proof is needed for it.
Roles
A valid session is the first gate; your account’s role is the second, read fresh
from the server on every call rather than from the token. Reads that spend no
model time and change nothing need viewer; anything that generates, writes,
dials out or places a call needs editor; the access and messaging-settings
methods need admin. A call above your role fails with PermissionDenied.
GetCurrentUser and Logout work for any signed-in account, so someone with no
role assigned can still see that and sign out.
Discover the schema
With PULSE_GRPC_REFLECTION=true on a local server:
grpcurl -plaintext localhost:52000 list
grpcurl -plaintext localhost:52000 describe pulse.v1.LeadServiceReflection is off by default and must stay off on deployed instances. Without
it, use the .proto files in grpc/api/proto/pulse/v1/.
Streaming calls
Every AI generator is a server-streaming RPC that returns stream StreamChunk:
| Field | Meaning |
|---|---|
text | The next piece of output. May be empty. |
is_final | True on the last chunk |
section | A section marker, for example positioning, swot, or grounding |
progress | 0.0 to 1.0 |
metadata | Extra key-value data |
agent_tasks | Actions the backend actually performed, such as a scrape. These are recorded facts, not model claims. A chunk with tasks may have no text. |
Long generations can go quiet while the model thinks. When a stream has been
silent for a while, the server sends a status frame so proxies do not drop
the connection and so you can tell waiting from stalled. A status frame has
empty text and is_final false — append text blindly and you append nothing
— and says what it is in metadata:
| Metadata key | Meaning |
|---|---|
keepalive | 1 on a frame that exists to keep the stream open |
phase | queued, generating, finishing, editing, refused, or at_capacity |
tokens | Tokens produced so far in the current pass, approximate |
token_budget | The ceiling this pass was dispatched with, not a prediction |
refused means a guardrail declined to release the output: a complete answer,
and the next move is to change the brief rather than retry it. at_capacity
means the inference plane is saturated, where retrying later is right.
Use a generous deadline: a long document can take tens of minutes on CPU.
When the model is busy and admission control is on, a call can fail with
ResourceExhausted. Retry after a few minutes.
Tie runs to your screen
Set x-agent-trace-id on your calls, and send the same value as session
in ActivityService/SubscribeAgentActivity. Then the activity stream shows
only the runs your client started. See Agent activity.
Errors
PULSE uses standard gRPC codes and puts a sentence meant for a person in the message. Common ones:
| Code | Typical cause |
|---|---|
Unauthenticated | Missing, expired, or revoked token |
PermissionDenied | Licence invalid, or your role does not allow the call |
FailedPrecondition | Something must be set up first, for example a HubSpot connection or PULSE_APPLY_ENABLED |
InvalidArgument | A required field is missing or has a bad value |
ResourceExhausted | Rate limit, or the inference plane is at capacity |
Unavailable | A dependency failed: HubSpot, GA4, speech synthesis, media storage |
Unimplemented | The feature does not exist in this deployment, for example still-image generation |
NotFound | No such record, or it belongs to another account |
Aborted | A long run ended in failure; the stream closes with this and the run’s own error |
See Troubleshooting for specific messages.
A2A: calling PULSE from another agent
PULSE publishes itself as an Agent2Agent (A2A) agent for FACE and the Runink TIDE fleet:
- Discovery:
GET /.well-known/agent-card.json. - Calls: JSON-RPC at
/a2a, with a PULSE session as a bearer token in theAuthorizationheader. Calls without a valid session are refused.
Choose a persona with the message metadata key skill. The default is
market-analyst.
| Skill | Persona |
|---|---|
market-analyst | Diagnostics, SWOT, positioning |
content-creator | Channel content |
copywriter | Long-form content and whitepapers |
strategy-agent | Prescriptive 30-day plans |
radar-agent | Trend and profile research |