Run discovery now
const url = 'https://api.sloose.com/orgs/org_9f3c/discovery/run?connector=con_8f2a';const options = {method: 'POST', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url 'https://api.sloose.com/orgs/org_9f3c/discovery/run?connector=con_8f2a' \ --header 'Authorization: Bearer <token>'Reads every module and field of the connection ?connector= names, through its stored grant, and writes a snapshot. Existing annotations are preserved; a field the CRM no longer returns is flagged as removed rather than deleted, so a template that mapped it still explains itself.
This route needs that connection to hold a working grant, because it runs with no browser present. It is not the only way to discover: connecting a CRM (POST /auth/orgs/{org}/connect) reads it with the token Zoho issues on the way through, which is how a new connection is discovered at all.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”The organisation id the session was issued for. A token for one organisation can never read another.
Example
org_9f3cThe organisation id the session was issued for. A token for one organisation can never read another.
Query Parameters
Section titled “Query Parameters”The connection this is about, by id: one of the organisation’s, or your own. REQUIRED: absent or empty is 400 CONNECTION_REQUIRED, listing the connections this bearer may name, because nothing picks one for a request that does not say (design §14.8). Any other — another organisation’s, or another person’s — is 404 CONNECTION_NOT_FOUND.
Example
con_8f2aThe connection this is about, by id: one of the organisation’s, or your own. REQUIRED: absent or empty is 400 CONNECTION_REQUIRED, listing the connections this bearer may name, because nothing picks one for a request that does not say (design §14.8). Any other — another organisation’s, or another person’s — is 404 CONNECTION_NOT_FOUND.
Responses
Section titled “Responses”The snapshot that was written, and how it differs from the one before it.
object
object
What changed against the previous run: modules and fields added, removed or altered.
Examplegenerated
{ "run": { "id": "example", "status": "example", "moduleCount": 1, "fieldCount": 1, "activeUserCount": 1, "errors": [ "example" ], "startedByUserId": "example", "createdAt": "example" }, "diff": "example"}The request named no connection (code: CONNECTION_REQUIRED, with connections: the ones this bearer may name). Nothing picks one for a request that does not say (design §14.8).
The error envelope every non-2xx answer uses.
object
Human-readable explanation.
Machine-readable reason. Absent on a few legacy 400s.
Examplegenerated
{ "error": "example", "code": "example"}No bearer, or one that no longer resolves: a session that is unknown or expired (code: AUTH_REQUIRED), or an API token that was revoked or expired (TOKEN_REVOKED, TOKEN_EXPIRED), whose organisation is gone (ORG_NOT_FOUND) or whose member or user row is (MEMBERSHIP_GONE).
The error envelope every non-2xx answer uses.
object
Human-readable explanation.
Machine-readable reason. Absent on a few legacy 400s.
Examplegenerated
{ "error": "example", "code": "example"}The bearer’s role is too low (code: ROLE_REQUIRED), or it was issued for a different organisation; the organisation has been closed (code: ORG_CLOSED, either kind of bearer); the person is banned (code: BANNED, a session); or it is a session that is signed in but in no organisation (code: NO_ORG): one that never joined one, or whose person was taken out of the one it was in, or left it. Signing in again changes nothing for NO_ORG; choosing or making an organisation does.
The error envelope every non-2xx answer uses.
object
Human-readable explanation.
Machine-readable reason. Absent on a few legacy 400s.
Examplegenerated
{ "error": "example", "code": "example"}?connector= names a connection this person may not use: another organisation’s, or another person’s (code: CONNECTION_NOT_FOUND).
The error envelope every non-2xx answer uses.
object
Human-readable explanation.
Machine-readable reason. Absent on a few legacy 400s.
Examplegenerated
{ "error": "example", "code": "example"}The connection holds no working grant — disconnected, or Zoho stopped honouring it — so there is nothing to read with. Reconnecting it reads the CRM straight away.
object
Examplegenerated
{ "error": "example", "code": "example"}Zoho is throttling how often this connection’s access is renewed — ten tokens from one grant in ten minutes — so the CRM was not asked (code: CONNECTION_THROTTLED). Retry-After says when to ask again; the connection is kept.
The error envelope every non-2xx answer uses.
object
Human-readable explanation.
Machine-readable reason. Absent on a few legacy 400s.
Examplegenerated
{ "error": "example", "code": "example"}The CRM could not be read (code: DISCOVERY_FAILED); the message says why, bounded to 500 characters. Or: Zoho could not renew the connection’s access — it did not answer, or it refused Sloose’s own client — so the CRM was not asked (code: CONNECTION_UNAVAILABLE). The connection is kept.
object
Example
{ "code": "DISCOVERY_FAILED"}The restore switch is on (code: MAINTENANCE): every route but /health and /robots.txt is refused before anything is read, except the operator’s own POST /staff/people/{id}/delete with the ADMIN_TOKEN. Sloose is down for maintenance. Please try again in a few minutes.
object
Example
{ "code": "MAINTENANCE"}Headers
Section titled “Headers”Seconds until asking again is worth it (300 while the switch is on).