Skip to main content

Tool Server Publishing

The single most important thing API Builder does: when an API definition is published, it's automatically registered as a Global Tool Server — the same list an admin would otherwise populate by hand via Admin Settings → Add Tool Server. No manual step, no copy-pasting an OpenAPI URL.

What registration actually does​

On publish, API Builder builds a Tool Server entry and appends it to TOOL_SERVER_CONNECTIONS (the same config list documented in OpenAPI Tool Servers):

  • Spec delivery — the API's OpenAPI spec is embedded inline (as JSON) in the entry rather than requiring a hosted /openapi.json URL.
  • Target URL — always the built-in API Gateway (/api/v1/api-definitions/{id}/proxy), whether or not the API has mappers. Rate limits, size caps, caller identity, masking, auditing and the network checks therefore apply to every published API.
  • Auth — a bearer key equal to the API's own gateway secret (generated on first publish, rotatable). The real upstream credential is never written into the Tool Server entry; only the gateway holds it.
  • Identity — the entry's id is api_{api_definition_id}, stored on the definition as tool_server_id so it can be found again on unpublish or rollback. The entry is also marked as an API Builder tool server, which tells Hrida.ai to attach a signed caller identity to each call.
  • Access — see Who can use a published API below.

Because execute_tool_server — the one code path every tool server call in Hrida.ai goes through — always builds its request as registered URL + OpenAPI route path, none of this requires any special-casing on the calling side. A published API Builder API is, from an agent's point of view, indistinguishable from any other Global Tool Server.

As a Global Tool Server, a newly published API follows the same rules as any admin-added one — see the OpenAPI Tool Servers guide: Global Tool Servers are hidden by default, and each user (or model config) still needs to explicitly enable it before it shows up as a usable tool.

Who can use a published API​

The Tool Server entry's access grants are set automatically on publish:

  • The API's owner and every member of its API Space get read access, so the people who build and govern an API can use it in their own agents.
  • Grants an admin adds by hand in Admin Settings → Tool Servers are kept on every re-registration.
  • Membership changes take effect immediately. Adding or removing a space member re-registers every published API in that space, so a removed member's grant is dropped straight away.
  • The gateway also re-checks the caller against these grants on every call, so a removed member is refused even in a conversation that started before they were removed.

A platform-wide API (no API Space) is granted only to its owner; admins can always use it.

What happens on un-publish or rollback​

The registration is removed whenever a published API stops being sanctioned for agents to call:

  • Pulled back to draft (or moved to staged by an admin) — its Tool Server entry is deleted.
  • Rolled back to a prior version — since rollback always resets status to draft, the registration is removed the same way, and only comes back once the rolled-back definition is reviewed and re-published.
  • Deleted — a definition can only be deleted while draft or rejected; if it still had a stale tool_server_id from a prior publish, that registration is unregistered first.

If a mapper is added, edited, or removed on an already-published API, the registration is refreshed immediately — you don't need to unpublish and republish for the mapper change to take effect on the next call. Because such a change goes live at once, only a lifecycle_manager, space_admin or admin can change mappers on a published API; developers pull it back to draft first.

Hrida.ai is proprietary software of Zlabs Innovation. See the license for terms. © 2026 Zlabs Innovation.