Partner API

Two credentials, and why

An organization key (ctx_org_...) provisions. It creates client workspaces, the people inside them and their keys, and it reads pooled usage. It can never read a client's memory.

A workspace key (ctx_sk_...) retrieves. It resolves to exactly one person, and every answer it gets is scored against that person's entitlement scopes. That is what makes it safe to hand to an agent: an agent holding Priya's key sees exactly what Priya sees.

Create one in the partner console, under Clients then Organization keys. That screen exists because you cannot mint the first organization key with an organization key. There is no CLI for provisioning: partners integrate server to server, and a second surface is a second thing to keep in step.

Provisioning a client

The first three calls are idempotent, on external_refand on email respectively, so you can run them on every one of your customer's logins rather than tracking which ones you have already created. The response says created either way.

# 1. A new client signs up in your product. Idempotent on external_ref,
#    so you can call this on every one of their logins.
curl -s https://www.contextely.com/api/v1/org/tenants \
  -H "Authorization: Bearer ctx_org_..." \
  -H "Content-Type: application/json" \
  -d '{"external_ref":"cust_8812","name":"Acme Ltd","query_cap":25000}'

# 2. One person inside that client. `scopes` is whatever your own
#    permission model says they may see.
curl -s https://www.contextely.com/api/v1/org/tenants/$TENANT/members \
  -H "Authorization: Bearer ctx_org_..." \
  -H "Content-Type: application/json" \
  -d '{"email":"priya@acme.example","role":"member","scopes":["finance:*"]}'

# 3. A key that speaks as exactly that person. Shown once. You store it.
curl -s https://www.contextely.com/api/v1/org/tenants/$TENANT/keys \
  -H "Authorization: Bearer ctx_org_..." \
  -H "Content-Type: application/json" \
  -d '{"member_id":"'$MEMBER'"}'

# 4. From here it is the ordinary product. This answer is scored
#    against Priya's entitlement, not against your key's.
curl -s https://www.contextely.com/api/v1/search \
  -H "Authorization: Bearer ctx_sk_..." \
  -H "Content-Type: application/json" \
  -d '{"query":"acme renewal date"}'

curl -s https://www.contextely.com/api/v1/org/usage \
  -H "Authorization: Bearer ctx_org_..."

No email is ever sent to a person you provision. They have no Contextely account, they are never invited to make one, and their row cannot be claimed by anyone who later signs up with the same address.

Caps, the pool, and what refuses

Each client has a cap you set. The organization has a pooled allowance of 250,000 retrievals and 40,000 refreshes a month. The two behave differently on purpose.

A hard stop at the included volume would turn a billing event into a simultaneous outage across every client you have, so the pool does not have one. Only a client's own cap and the runaway ceiling refuse.

curl -s https://www.contextely.com/api/v1/org/tenants/$TENANT \
  -H "Authorization: Bearer ctx_org_..." \
  -H "Content-Type: application/json" \
  -d '{"query_cap":50000}'

Every endpoint

All under /api/v1, all taking an organization key. Asking for a client that belongs to a different organization answers not_found, the same as asking for one that does not exist: a distinguishable refusal would tell you which of your competitors is also a customer.

Generated from the same catalogue as the OpenAPI document, so neither can describe an endpoint that does not exist.

What you cannot do

There is no endpoint that returns a client's memory objects to an organization key, and no way to act as one of their people from the console. Your staff are not members of your clients' workspaces.

When you need to debug, mint a key for a person inside that client and use it. That leaves an entry in their own retrieval log, which you can read with GET /org/tenants/{id}/audit. It is the accountable path rather than the convenient one, and it is worth telling your own customers about.