# BUFI developer API

## When to use this API

Use the public API to discover opted-in workspace portfolios and exact browser
tool contracts. Reads are free and require no API key. They contain published
profiles and schemas, never private workspace transactions or account balances.

- [OpenAPI specification](/openapi.json)
- [HTML developer guide](/developers)
- [Authentication and permissions](/auth.md)
- [Agent skills](/.well-known/agent-skills/index.json)

## Example requests

    curl -sS https://app.bu.finance/api/public/agents?offset=0
    curl -sS https://app.bu.finance/api/public/tools
    curl -sS https://app.bu.finance/api/public/tools/read_public_invoice

The directory returns profiles and pagination with nextOffset. It accepts q for
search and offset for pagination; portfolio surfaces are described in OpenAPI.
The tool catalog returns a count and tools with unique names, descriptions and
inputSchema. To use a tool, navigate to the appropriate browser surface and
enumerate its currently registered WebMCP tools. The catalog has no POST method
and cannot execute a financial action.

## Errors and permissions

Unknown tool names and nonexistent API paths return HTTP 404 with structured
JSON code, message and hint fields. Public directory errors retain the error
field for existing clients, with code, message and hint for automated recovery.
Use the actual HTTP status to distinguish invalid input, absence, rate limits
and temporary service failures. Follow Retry-After where supplied.

The public directory is rate limited; the OpenAPI specification documents its
enforced input limits and responses. No dedicated financial sandbox, public
OAuth grant or self-serve client registration is advertised. Private financial
operations keep the existing session, workspace permissions and human approval
requirements. Reading a definition grants no permission to invoke it.