Skip to main content

Relative API URLs for Tools

When configuring API tools, you can use relative URLs (like /api/v1/endpoint) instead of full absolute URLs. At runtime, relative URLs are resolved against the domain of the client making the request — not the Devs.ai domain. This is especially useful for embedded deployments where your agent's tools need to call APIs on the hosting platform's domain.

Why Relative URLs?​

If Devs.ai is embedded into a platform like a marketplace, an API tool might need to call that platform's own endpoints. With absolute URLs, you'd need to update the tool configuration for every environment (development, staging, production). With relative URLs, the same configuration works everywhere — the tool automatically calls the right domain based on where the request originates.

Example:

EnvironmentClient originTool URL /graphql resolves to
Developmenthttps://dev-marketplace.example.comhttps://dev-marketplace.example.com/graphql
Staginghttps://staging-marketplace.example.comhttps://staging-marketplace.example.com/graphql
Productionhttps://marketplace.example.comhttps://marketplace.example.com/graphql

Absolute URLs (https://api.external.com/v1) continue to work exactly as before — they're used as-is regardless of where the request comes from.

Setting Up a Tool with a Relative URL​

  1. Navigate to your agent's Tools configuration.
  2. Create or edit an API tool (REST or GraphQL).
  3. In the API URL field, enter a relative path starting with /:
    • /api/v1/endpoint
    • /graphql
  4. Save the tool.

The URL field accepts both formats — a helper text explains what each one does.

URL Validation Rules​

  • Relative URLs must start with /
  • Paths like api/v1/endpoint (without a leading /) are not accepted
  • Double slashes in the path (e.g., /api//v1) are not allowed
  • Absolute URLs must use HTTPS

How the Origin Is Determined​

When a request arrives, the system determines the client's origin in this order:

  1. Origin header — the preferred source, automatically set by browsers on cross-origin requests
  2. Referer header — used as a fallback; the origin is extracted from the full URL
  3. Devs.ai host — final fallback if neither header is present (e.g., for server-to-server calls)

For embedded deployments, the browser automatically sends the correct Origin header, so relative URLs resolve to the right domain without any extra configuration.

Good to Know​

  • Absolute URLs are unchanged. If your tool is configured with a full URL like https://api.example.com/v1, it works exactly as before regardless of the client origin.
  • Server-to-server calls may need attention. If you're calling the Devs.ai API from a backend (without Origin or Referer headers), relative URLs will fall back to the Devs.ai host. For these cases, use absolute URLs instead.
  • No per-tool origin override. The origin is always determined from the incoming request. If a tool needs a fixed base URL, use an absolute URL.
  • HTTPS is not enforced for relative URLs. The protocol comes from the client origin at runtime. If the client uses HTTP, the resolved URL will too.