Make your first API request

Make your first API request

Read a page of records from a sandbox company using an application-scoped Bearer token. You need the object’s internal name and permission to read it.

Base URL

The production API base is https://v2.api.caraer.com/api/v2. The OpenAPI server is https://v2.api.caraer.com; its paths already include /api/v2, so combine them once.

Authentication

For an installed app or OAuth app connection, send:

Authorization: Bearer <app-token>

App tokens identify their installation’s company and granted permissions. Hosted app invocations receive a short-lived installationToken; use its fresh value and injected caraerApiBase. See app functions.

For a human user’s Bearer token, also send X-Caraer-Company-Uuid: <company-uuid> on company-specific requests. The user must have access to that company. Record and property permissions still apply.

Keep private tokens on the server and out of source control and logs. Public forms use public identifiers; never expose your private token in a browser.

Test endpoints with your private app

The API reference can sign you in through Caraer OAuth and attach the resulting Bearer token to test requests. Use a sandbox company: requests go directly to the production API, and write endpoints change real data.

1. In Caraer, create a private app with authentication method OAUTH2. Existing API-key or managed-token apps cannot change authentication method; create a separate OAuth app when needed.
2. In the app’s OAuth 2.0 settings, add this exact redirect URI and save: https://developer.caraer.com/oauth/callback.
3. Copy the Client ID. Keep the client secret private; this browser flow uses SHA-256 PKCE and does not need the secret.
4. Open an endpoint’s Authentication panel in the API reference. Configure Private app OAuth with your Client ID, leave Client Secret empty, and keep Use PKCE set to SHA-256. Use Authorize to sign in to Caraer and approve the permissions on its consent screen.
5. Keep Bearer selected and send a read request first. The OAuth shortcut fills that Bearer token automatically. The connection uses the private app’s owning company; no X-Caraer-Company-Uuid header is needed for this app token.

The app installation’s permissions still apply. An app with no declared permissions lets you choose permissions on the Caraer consent screen; an empty grant denies access. Requests cannot exceed the installation’s grants.

Credentials stay in the API reference’s page memory and are not saved between page loads. Reload to clear them, or clear the token in Authentication. Clearing the page does not revoke an already issued token: use Caraer’s POST https://v2.api.caraer.com/oauth/revoke endpoint to revoke it. Access tokens last about one hour; authorize again when needed. The documentation server and the public documentation MCP do not receive your credentials or execute these requests.

If authorization fails, check that the app is OAuth-enabled, its Client ID is correct, and the redirect URI matches exactly. Allow the sign-in popup and keep it open until the reference closes it. On 403, check the installation’s permissions rather than adding a company header or granting every permission.

Read a page of records

Set CARAER_TOKEN to a sandbox app token in your shell. This example assumes an object named candidate that the installation can read:

curl -X POST 'https://v2.api.caraer.com/api/v2/records/index' \
  -H "Authorization: Bearer $CARAER_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"mainObject":"candidate","page":1,"limit":10}'

Expect a successful response containing the first page of accessible records. An empty page can be correct; it says nothing about another company’s data. On 401, check the token. On a permission error, inspect installation grants and object/property access rather than blindly retrying.

Continue building

• Understand the data model.
• Choose fields and add filters.
• Create and update records.
• Browse the API reference.