Skip to main content

Using project services

Your application can use the services in its Intellectible project rather than building every supporting feature itself. For example, it can call a workflow to process a document, store records in a project database, and retrieve files from the Library.

The public API is the connection between your code and these services. The agent can help find the relevant endpoints and build the integration.

The module's project API key​

A new module is created with its own project API key, initially granting no service permissions. Authentication identifies the project; permissions determine what the application can do there.

Open the project's API keys section to review and grant the operations you need. For example, allow the application to run a particular workflow without giving it permission to delete Library files.

In the module, Dev Machine → Overview → Project API key shows the associated key and its permissions. The Use key control can select another eligible project key. Only keys made available to code running on Intellectible can be supplied this way.

Read credentials from the environment​

The development machine and deployments receive these variables when configured with a usable project key:

VariablePurpose
INTELLECTIBLE_PROJECT_API_KEYThe credential used for public API calls.
INTELLECTIBLE_PROJECT_IDThe project the credential belongs to.
INTELLECTIBLE_PUBLIC_API_URLThe public API base URL.
INTELLECTIBLE_PROJECT_API_KEY_FILEA file containing the credential, for tools that read it from disk.

Read the values in server-side code. Send the key in the Authorization header as-is, without a Bearer prefix. Use the endpoint reference for the request path, body, and required permissions.

Do not print the key, paste it into agent conversations, commit it, or expose it through browser-side environment variables. An application's users should call your backend; your backend decides what they are allowed to do before using its project credential.

Choose the service you need​

  • Workflows: run reusable processing logic with inputs and outputs.
  • Databases: query or update structured project data.
  • Library: upload, retrieve, and manage project files.
  • AI services: use supported model, embedding, and reranking endpoints.

See the Public API reference and API permissions guide for the available operations. API-key permissions are separate from application-user roles: a powerful backend key does not mean every signed-in user should be allowed to exercise all its powers.

Key changes and troubleshooting​

Changing the key associated with a module requires a development-machine restart to load the new environment. Redeploy running deployments when changing or rotating the credential they use; changing the configuration does not rewrite an already-running process's environment.

For failed API requests:

  • 401 usually means the credential is missing, invalid, disabled, or incorrectly formatted. Check that you have not added a Bearer prefix.
  • 403 means the request does not have the required permission. Review the key's scopes, including any restrictions to individual resources.
  • If a previously working integration fails after a key change, check whether the machine or deployment is still using the old credential.

Start with one small, authorised operation and handle error responses before building a larger integration.