# API conventions ## API conventions Aeeron is designed for agent traffic, which means the API favors explicit state over convenience shortcuts. The interface needs to describe not only what action is being requested, but also whether the action has been priced, whether it has been funded, whether execution has started, and whether a retry should be interpreted as a replay or a new intent. Those semantics are more important for agent systems than for human-driven dashboards because the caller has to make decisions programmatically. ### Core objects Most flows revolve around four core objects: a `quote`, which captures pricing and payment requirements; a `payment`, which proves that the quote has been funded; an `execution`, which represents the running or completed action; and a `result`, which contains provider output or a terminal failure. Separating these objects gives the client a stable mental model and prevents hidden coupling between economic state and provider state. ### Execution model Aeeron treats most paid actions as asynchronous because that is how real providers behave. Company formation, server provisioning, and service delivery all involve external work that may take seconds, minutes, or much longer. A successful request therefore means the execution has been accepted and is now tracked, not that the provider has already produced the final artifact. This distinction is essential for agent runtimes, which need to continue reasoning after the initial acceptance response. ### Status values Executions move through a stable lifecycle so client policy can key off status without depending on provider-specific wording. ```json { "status": "pending | processing | completed | failed | refunded" } ``` ### Idempotency Every state-changing request should carry an idempotency key, and that key should represent one business intent only. If a network timeout occurs while the client is creating a quote or execution, the same key should be reused for the retry. If the agent changes the payload or decides on a different action, a new key should be created. This rule is what prevents retries from becoming double charges or duplicate provider operations. ### Timeouts and polling Agent clients should use short request timeouts and then move to polling or webhook reconciliation for long-running work. Blocking a single process until a provider finishes is fragile and makes failure classification harder. A tracked execution resource gives the caller a much cleaner way to resume, reconcile, and audit long-running jobs. ```bash curl https://api.aeeron.com/v1/executions/exe_3d7a9e \ -H "Authorization: Bearer $AEERON_API_KEY" ``` ### Object design Aeeron keeps the outer resource envelope compact and pushes action-specific variability into `input`, `output`, and `providerMeta`. That design lets different provider categories coexist without forcing the client to relearn the surrounding object model every time it moves from infrastructure to legal formation or to agent service purchase. ### Recommended client behavior In practice, a good client validates budgets before it requests a quote, treats `payment_required` as an expected branch rather than an exception, persists execution identifiers immediately, retries network failures with the same idempotency key, and routes terminal failures back into policy logic instead of letting the model improvise around them. Those habits matter more than language choice or framework choice because they define whether the integration is safe under real operating conditions. --- # 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-conventions.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.