How does an AI agent integrate with URBLD?
An AI agent discovers URBLD's capabilities by fetching /.well-known/ai-capabilities.json and /openapi.json, authenticates with OAuth 2.0 client_credentials scoped to one organization, and calls REST endpoints under https://api.urbld.com/v1. Every mutation is signed to the actor identity and recorded to the tenant audit log.
Discovery
Before it ever calls an endpoint, a well-behaved agent should fetch:
/.well-known/ai-capabilities.json— a machine-readable manifest listing every capability, its OAuth scopes, and its risk tier./agent.json— an integration profile with contact info, rate limits, and MCP endpoint (when available)./openapi.json— the full OpenAPI 3.1 spec./llms.txt— a compact index for LLM crawlers.
Authorization model
Every URBLD access token is bound to exactly one organization and carries a set of granular scopes. Agents should request the smallest scope set that satisfies their task — the platform's AI Integrity Monitor logs and evaluates every scope escalation.
const token = await getToken({
grant_type: "client_credentials",
scope: "leads.read scheduling.read scheduling.write communications.write",
});Grounding for AI reads
URBLD's own Jarvis agent is quantitatively grounded — it must call structured tools for every count or list and cannot hallucinate metrics. Third-party agents should follow the same discipline:
- Never summarize counts from prose — always call the corresponding
.readendpoint. - Cache tenant-scoped data locally only for the current request; purge on identity shift.
- When asked "how many X", call the endpoint. When asked "which X", call the endpoint. Return the raw number in your answer.
Auditability
Every mutation an agent performs is recorded to ai_audit_logs with the resolved actor identity, entity IDs, before/after values, and the scope stack that authorized the call. Owners can trace exactly what any agent did, when, and why.
Rate limits & back-pressure
Agents share the tenant's rate budget with human traffic. On 429 Too Many Requests, respect the Retry-After header and back off exponentially. Bursty agents should implement a token-bucket on the client side to avoid starving human users of the same organization.
Recommended next reads
- Business OS API — the full lifecycle as one surface.
- AI Agent Infrastructure — the platform layer that makes agents safe.
- Governor — how URBLD monitors AI actions in real time.
Frequently Asked Questions
Straight answers about how URBLD runs the business end-to-end.