Conventions & errors

How Yurbi API requests and responses are shaped: status codes, error reporting, response envelopes, and the lookup values used throughout the reference.

Requests

Every endpoint in this reference is a POST carrying a JSON body, and every authenticated call takes the session token as a field in that body rather than a header:

curl -X POST "https://your-yurbi-server.com/api/Session/CheckSession" \
  -H "Content-Type: application/json" \
  -d '{ "sessionToken": "YOUR_SESSION_TOKEN" }'

Platform: where Yurbi is served

Endpoint paths are case-insensitive.

Status codes

Yurbi reports application errors in the response body with a 200 status. The HTTP status tells you whether the request reached the endpoint, not whether it succeeded.

A 204 with an empty body is the most common sign of an expired token. Confirm with CheckSession.

Error reporting

Most endpoints return an envelope with ErrorCode and ErrorMessage, where 0 means success:

{ "ErrorCode": 0, "ErrorMessage": "" }

Three variations appear across the API:

• Per-item errors. List endpoints return a bare array, and each item carries its own ErrorCode. There is no wrapper object around the array.
• Alternative field names. Some endpoints use ERROR_CODE / ERROR_MESSAGE, error_code / error_message, returncode / message, or Code / Message. Each endpoint page shows the shape it returns.
• HasError on report execution. GetReportData reports failures through HasError and leaves ErrorCode at 0. When you run a report, branch on HasError.

Error codes

Bare values

Some endpoints return a single value rather than an envelope, and that value is served as plain text, not JSON. JSON.parse() will fail on these responses — read the body as text instead.

POST /api/library/FavReport            ->  0
POST /api/RegServers/TestConnection    ->  Passed
POST /api/Group/AddUser                ->  User Added Successfully.
POST /api/LicenseManager/GetInstallationID
                                       ->  4446-4836-3034-3631-4452-3666

DoLogout returns 0, GetSQL returns the generated SQL, and TestConnection returns Passed or a failure message. Each endpoint page shows its exact response.

An empty array means either no matching records or a rejected token, so check the session when an empty result is unexpected.

Working with objects: fetch, modify, send

Endpoints that create, update or delete an object take the whole object, not an ID. The pattern is the same throughout the API:

1. Fetch a starting object — a New… template when creating, or a Get… call when changing or removing something that exists.
2. Modify the fields you care about.
3. Send the complete object back.

# create a user
POST /api/Contact/NewContact      -> template
POST /api/Contact/SaveContact     -> { user: <filled template> }

# delete a user
POST /api/Contact/GetContactList  -> find the user object
POST /api/Contact/DeleteContact   -> { user: <that whole object> }

Building an object by hand tends to omit collections the endpoint expects, which surfaces as ErrorCode 9000. Starting from a template avoids that, and keeps your integration working as fields are added in later releases.

Create and update are the same call on most objects, distinguished by the identifier: send null (or "" for reports) to create, or an existing ID to update.

Permissions and the super-admin account

The built-in admin account is a super-admin. It bypasses application and group permissions entirely, so every API call succeeds regardless of how content is scoped.

Every other administrator is subject to permissions, including one you add to the Administrators group. Before an integration user can work with an application through the API, grant it a role on that application — Architect for App Builder work, for example — and add it to the groups whose content it needs to reach. If you register a new application, existing administrators will not see it until they are granted a role on it.

This matters when moving from a proof of concept to production: work that succeeded under admin can return empty results or 204 responses under a purpose-made service account that has not been granted access.

Response size

Responses are not paged. Several endpoints return substantially more than they appear to:

• DoLogin returns around 200 KB, most of it the interface phrase table.
• GetApplicationList and GetAllSecurityGroups embed full user records for everyone they touch.
• GetReportData returns every row the report produces. A detail report over a large table can return several megabytes.

Where volume matters, run reports built with a TopN limit or an aggregate rather than fetching detail rows and reducing them in your own code.

Field type codes

Report metadata describes each field with a short code, in Fieldtype and yurbitype. The full list is available from GetDataTypes.

Date codes are not interchangeable. dat carries a time component and is offset for the viewer's timezone; doz is a plain date and is returned exactly as stored.

Output types

A report's OutputType — and the itemtype returned in library listings — identifies how the report is rendered. The current list is available from GetOutputTypes.

Library listings return dashboards alongside reports, with itemtype 0. Filter them out before passing IDs to report endpoints.

Roles

Roles 1–4 control what a user may do with content in folders scoped to a group. Roles 5–7 are assigned per application through UserApplications on SaveContact and consume a licence seat.

Cross-origin requests

The API returns Access-Control-Allow-Origin: *, so browser-based applications can call it directly. Because the session token travels in the request body, authenticate on your server rather than exposing credentials in client-side code.