# API endpoints ## API endpoints Aeeron exposes a payment-aware API surface built for agent control loops rather than human checkout flows. The endpoint layout separates discovery, pricing, payment, execution, and provider-specific action surfaces so the client can reason clearly about what stage of work it is in. That separation is deliberate. An agent should know whether it is still evaluating an action, funding it, or waiting for a provider result. ### 1. List supported actions `GET /v1/actions` This endpoint returns the action catalog that an agent can use during planning. It is the right place to discover which operations are currently available, which of them support asynchronous execution, and which categories the integration can rely on without hardcoding provider-specific assumptions into prompt logic or policy logic. ```json { "items": [ { "name": "companies.create", "supportsAsync": true }, { "name": "servers.provision", "supportsAsync": true }, { "name": "agent-services.purchase", "supportsAsync": true } ] } ``` ### 2. Get action details `GET /v1/actions/{actionName}` This endpoint returns the schema, pricing model, and budget hints for a single action. In practice, clients use it to validate inputs, decide whether an action is safe to expose to the model, and map one abstract capability such as `buy compute` or `form company` to a concrete Aeeron action name with a known input contract. ### 3. Create a quote `POST /v1/quotes` This endpoint prices a requested action before payment is attempted. The quote is where budget logic should anchor, because it gives the client a concrete amount, currency, and expiry window instead of forcing it to reason about provider pricing heuristics on its own. ```json { "action": "companies.create", "input": { "jurisdiction": "US-DE", "companyType": "llc", "name": "Atlas Compute LLC" }, "budget": { "amount": "220.00", "currency": "USDC" } } ``` ### 4. Prepare payment `POST /v1/payments/prepare` This endpoint creates the x402 payment challenge from a quote. It converts a pricing decision into a funding requirement that can be consumed by a wallet or payment subsystem without losing the original action context. ### 5. Confirm payment `POST /v1/payments/confirm` This endpoint attaches payment proof to the quote and marks it ready for execution. It is useful in architectures where payment preparation and execution happen in separate components or separate trust zones, because the payment event can be recorded before the provider call is launched. ### 6. Create an execution `POST /v1/executions` This endpoint starts a paid action after payment has been verified. The server returns an execution record immediately even when the provider task itself is long-running, which gives the client a durable handle for polling, reconciliation, and later audit. ### 7. Get execution status `GET /v1/executions/{executionId}` This endpoint returns the current status, provider metadata, and final output when available. Clients should treat it as the canonical resource for long-running work, even when webhooks are enabled, because it provides the final source of truth for completion and failure state. ### 8. Create a company `POST /v1/companies` This endpoint launches a company-formation workflow through a supported provider. It is typically used after an agent has selected jurisdiction, entity type, and ownership details and has already passed the spend policy checks associated with legal and operational setup. ```json { "jurisdiction": "US-DE", "companyType": "llc", "name": "Atlas Compute LLC", "owners": [ { "type": "person", "fullName": "Mira Chen", "country": "SG" } ], "registeredAgent": true } ``` ### 9. Get company record `GET /v1/companies/{companyId}` This endpoint returns formation status, provider references, and generated documents for a previously created company workflow. It is useful when an agent needs to consume downstream artifacts such as registration documents, filing confirmations, or follow-up references needed by later actions. ### 10. Provision a server `POST /v1/servers/provision` This endpoint provisions a compute instance that the agent can use immediately or reserve for later work. It fits runtime scaling, burst compute, scheduled jobs, and chained workflows where one paid infrastructure step enables a later model or data-processing step. ```json { "region": "fra1", "plan": "gpu-small", "image": "ubuntu-24.04", "durationHours": 24, "sshKeys": ["ssh-ed25519 AAAA..."] } ``` ### 11. Renew server time `POST /v1/servers/{serverId}/renew` This endpoint extends a running or reserved compute allocation. It is useful when an agent needs to preserve continuity for a workload it has already launched and wants to make a bounded renewal decision rather than recreate the environment from scratch. ### 12. Register a domain `POST /v1/domains/register` This endpoint lets an agent secure a domain as part of a launch or deployment workflow. Domain purchase is a good fit for Aeeron because it has a clear price boundary, an external provider, and a result that often matters to later infrastructure and branding steps. ### 13. Purchase storage `POST /v1/storage/purchase` This endpoint purchases additional object or archive storage for workloads that need durable retention. It is especially useful for agents that produce artifacts over time and need a simple way to increase storage without embedding provider-specific billing logic into the workflow engine. ### 14. Search agent services `POST /v1/agent-services/search` This endpoint searches available agent services by task type, price band, or service guarantees. It allows one agent to evaluate external paid capabilities before making a purchase decision, which is a necessary step in any serious multi-agent market or delegation model. ### 15. Purchase an agent service `POST /v1/agent-services/purchase` This endpoint purchases output from another agent or provider through the same payment-backed execution model. The benefit is that outsourced work remains economically explicit and operationally tracked, rather than disappearing into a one-off marketplace call with no shared lifecycle. ```json { "serviceId": "svc_due-diligence-v2", "task": "Research EU hosting providers with GPU stock this week.", "maxPrice": { "amount": "45.00", "currency": "USDC" }, "deliveryMode": "json" } ``` ### Notes on the endpoint surface Taken together, these endpoints define a surface that is built around planning before spending and reconciling after execution. The client can discover capabilities, price them, fund them, execute them, and then inspect the resulting state without collapsing those steps into one opaque provider request. That is what makes the API suitable for agent systems that need both autonomy and operational discipline. --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://aeeron.gitbook.io/aeeron-docs/api-endpoints.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.