# Skills for AI Agents (/skills-for-agents) A CLI-first capability map and decision tree for LLM-based callers. **Read this before making your first request** — it is shorter than the reference docs and will save you from probing endpoints that are empty by design. If you are the developer wiring an agent up to e-Próspera, paste this page (or `/llms-full.txt`) into your agent's system prompt or skill folder. Official CLI: [Honduras-Prospera-inc/eprospera-cli](https://github.com/Honduras-Prospera-inc/eprospera-cli). ## TL;DR — what an agent must internalize before the first call [#tldr--what-an-agent-must-internalize-before-the-first-call] * **Use the CLI first when shell access is available:** `eprospera --json --yes `. * **Docs, in order:** [CLI](/cli) (install, auth, exit codes) → [Standard API Keys](/standard-keys), [Agent Keys](/agent-keys), or [OAuth](/oauth-overview) (credentials & scopes) → [Conventions](/conventions) (HTTP rules) → this page (capabilities & dead ends) → [Agent recipes](/agent-recipes) (copy-paste workflows). * **Every Agent Key request is scope-checked.** CLI exit code `4` or HTTP `403` means the key is missing the scope, **not** that the resource is absent. * **A `404` / CLI exit code `5` from legal-entity reads usually means "created outside the API"**, not "no such entity." Agent Keys can only see API-created records — see [Why your call might return empty](#why-your-call-might-return-empty). * **Consented entities and tax records require OAuth.** They are read-only and limited to the signed-in user or selected entities the user still represents. * **There are no webhooks.** Use `eprospera application watch --timeout 30m` or poll the direct API — see [Polling, not webhooks](#polling-not-webhooks). ## Invocation Rules [#invocation-rules] Prefer this shape for automation: ```bash eprospera --json --yes ``` * Parse stdout as JSON. Treat stderr as diagnostics. * Use `--raw` when compact single-line JSON is better. * Use `--fields id,statusId,name` to reduce read responses. * Use `--dry-run` before write commands while constructing request files. * Put credentials in `--api-key`, `EPROSPERA_API_KEY`, or `auth login`; never echo tokens. * Use `EPROSPERA_ENV=staging` for staging checks. * Use direct HTTP only when the CLI does not cover the task or you are implementing your own client. ## CLI Capability Matrix [#cli-capability-matrix] | I want to… | Run | Credentials | Required scope | Common dead-end | | ------------------------------- | ----------------------------------------------------------------------------------------- | ------------ | ----------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | | Confirm an RPN exists | `eprospera --json entity verify ` | `sk-`, `ak-` | `agent:verify_rpn` | RPN must be 14 digits starting with 8 or 9. | | Search the registry | `eprospera --json entity search ""` | `sk-`, `ak-` | `agent:registry.search` | Empty results are not a bug; broaden or simplify the query. | | Fetch one legal entity | `eprospera --json entity get ` | `sk-`, `ak-` | `agent:entity.read` | Agent Keys see only API-created entities; `sk-` sees any you represent. | | Fetch entity documents | `eprospera --json entity documents ` | `sk-`, `ak-` | `agent:entity.documents.read` | Same visibility as `entity get`. | | List owned applications | `eprospera --json application list` | `sk-`, `ak-` | `agent:entity.application.read` | Agent Keys see only API-created records; `sk-` sees all owned. | | Create an LLC application | `eprospera --json --yes application create --file application.json` | `sk-`, `ak-` | `agent:entity.application.create` | JSON fails schema validation, or AOC was not pre-accepted. | | Fetch an application | `eprospera --json application get ` | `sk-`, `ak-` | `agent:entity.application.read` | Agent Keys require an API-created application; standard keys can read all owned applications. | | Pay with a voucher | `eprospera --json --yes application pay --voucher ` | `sk-`, `ak-` | `agent:entity.application.pay` | Voucher must fully cover the invoice. | | Create hosted checkout | `eprospera --json --yes application checkout --redirect-url --provider ` | `sk-` | — | Agent Key checkout is disabled. | | Watch for approval | `eprospera --json application watch --timeout 30m` | `sk-`, `ak-` | `agent:entity.application.read` | Rejected/payment-failed states are terminal. | | Read the owner's profile | `eprospera --json me profile` | `ak-`, OAuth | `agent:person.details.read` / `eprospera:person.details.read` | Standard `sk-` keys are not valid for `me` commands. | | Read residency status | `eprospera --json me residency` | `ak-`, OAuth | `agent:person.residency.read` / `eprospera:person.residency.read` | Missing residency-read scope. | | Read ID-verification artifacts | `eprospera --json me id-verification` | `ak-`, OAuth | `agent:person.id_verification.read` / `eprospera:person.id_verification.read` | Signed URLs expire; download promptly. | | List consented entities | `eprospera --json me legal-entities list` | OAuth | `eprospera:entity.read` | An empty list is valid when no entities were selected. | | Read a consented entity | `eprospera --json me legal-entities get ` | OAuth | `eprospera:entity.read` | Consent and current representation are both required. | | Read consented entity documents | `eprospera --json me legal-entities documents ` | OAuth | `eprospera:entity.documents.read` | Consent and current representation are both required. | | Show tax obligations | `eprospera --json tax status --subject ` | OAuth | `eprospera:person.tax.read` or `eprospera:entity.tax.read` | Scope must match `personal` or the selected entity. | | List tax filings | `eprospera --json tax list --subject --year 2025` | OAuth | `eprospera:person.tax.read` or `eprospera:entity.tax.read` | Cursors are opaque; never edit or decode them. | | Read one tax filing | `eprospera --json tax get ` | OAuth | `eprospera:person.tax.read` or `eprospera:entity.tax.read` | The filing must be visible to the current grant. | | Download a tax document | `eprospera tax download --document assessment` | OAuth | `eprospera:person.tax.read` or `eprospera:entity.tax.read` | Output contains confidential financial information. | | List referral attribution | `eprospera --json referral list ` | `sk-` | — | Agent Keys are not valid for referral reads. | | Submit a visitor pass | `eprospera --json --yes visitor-pass create ` | None | — | All applicant fields and explicit consent are required. | ## Direct HTTP Mapping [#direct-http-mapping] When you cannot use the CLI, call the underlying endpoints directly. All paths are relative to `https://portal.eprospera.com` in production or `https://staging-portal.eprospera.com` in staging. | CLI command | Direct endpoint | | ------------------------------------------------- | -------------------------------------------------------------- | | `entity verify ` | `POST /api/v1/verify_rpn` | | `entity search ""` | `POST /api/v1/registries/legal_entities/search` | | `entity get ` | `GET /api/v1/legal_entities/{id}` | | `entity documents ` | `GET /api/v1/legal_entities/{id}/documents` | | `application list` | `GET /api/v1/legal_entity_applications` | | `application create --file application.json` | `POST /api/v1/legal_entity_applications` | | `application get ` / `application watch ` | `GET /api/v1/legal_entity_applications/{id}` | | `application pay --voucher ` | `POST /api/v1/legal_entity_applications/{id}/pay/voucher` | | `application checkout …` | `POST /api/v1/legal_entity_applications/{id}/checkout_session` | | `me profile` | `GET /api/v1/me/natural-person` | | `me residency` | `GET /api/v1/me/natural-person/residency` | | `me id-verification` | `GET /api/v1/me/natural-person/id-verification` | | `me legal-entities list` | `GET /api/v1/me/legal-entities` | | `me legal-entities get ` | `GET /api/v1/me/legal-entities/{id}` | | `me legal-entities documents ` | `GET /api/v1/me/legal-entities/{id}/documents` | | `tax status` | `GET /api/v1/me/tax/summary` | | `tax list` | `GET /api/v1/me/tax/filings` | | `tax get ` | `GET /api/v1/me/tax/filings/{filingId}` | | `tax download …` | `GET /api/v1/me/tax/filings/{filingId}/documents/{document}` | | `referral list ` | `GET /api/v1/referral-codes/{code}/referrals` | | `visitor-pass create …` | `POST /api/v1/visitor_pass_applications` | The legal-entity portfolio and tax endpoint families are OAuth-only. Agent Keys cannot use them. Consent limits entity access to the user's selection, and the corresponding personal or entity tax scope is required for every tax request. ## Decision Tree — Pick the Right Command [#decision-tree--pick-the-right-command] Walk this top-down. Stop at the first row that matches your goal. 1. **You need to store or inspect credentials.** → `eprospera auth login`, `eprospera --json auth whoami`, or `eprospera --yes auth logout`. 2. **You have an RPN string and want to know if it is real and active.** → `eprospera --json entity verify `. 3. **You have a human-readable name or partial RPN and want to find the entity.** → `eprospera --json entity search ""`. If results are empty, broaden the query — do not retry the same input. 4. **You have a legal-entity ID that your own agent created earlier.** → `eprospera --json entity get `. 5. **You have a legal-entity ID from outside this API.** → **Not reachable with an Agent Key.** A standard `sk-` key can still `entity get` any entity you currently represent. Otherwise use OAuth and `/api/v1/me/legal-entities/{id}`. Do not retry the Agent Key call. 6. **You want data about the human who owns the Agent Key or OAuth credential.** → `eprospera --json me profile`, `me residency`, or `me id-verification` with the matching scope. 7. **You want entities the OAuth user selected during consent.** → `eprospera --json me legal-entities list`, then `get` or `documents` with a returned ID. 8. **You want personal or consented-entity tax data.** → Log in with OAuth, then use `tax status`, `tax list`, `tax get`, or `tax download`. Use `--subject personal` or a consented entity UUID. 9. **You want to incorporate a new LLC.** → See [Recipe 2](/agent-recipes#recipe-2-fully-automated-llc-incorporation). Confirm MoW, pre-accepted AOC, and a fully covering voucher before the agent starts. 10. **You want the resident to pay through hosted checkout.** → Use `application checkout` with a standard key. Agent Keys cannot create checkout sessions. 11. **You want to know when an application is approved.** → `eprospera --json application watch --timeout 30m`. 12. **You need referral attribution or a public visitor pass.** → Use `referral list` with a standard key or `visitor-pass create` without a credential. 13. **You need exact wire-level request and response shapes.** → Use the direct HTTP reference pages. ## Why Your Call Might Return Empty [#why-your-call-might-return-empty] Read this section any time a response is unexpectedly empty, `404`, CLI exit code `5`, `401`, `403`, or CLI exit code `4`. Most of these are **by design**, not bugs. | Symptom | Cause | Fix | | -------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- | | `application list` returns `{ "data": [] }` | Agent Keys see **only API-created applications** (`createdViaAPI: true`). Applications started in the portal are invisible to `ak-` keys. Standard `sk-` keys list every owned application. | Restart through the API/CLI, or have the owner finish it in the portal. A standard key can still *read* the portal draft. | | `entity get ` exits `5` or HTTP returns `404` | Either the entity does not exist, or (for Agent Keys) it was created outside the API. Standard keys return any entity the owner currently represents. | Use a standard key, or OAuth `/me/legal-entities/{id}` if the owner must share non-API-created entities. | | `/me/legal-entities*` returns `401` | You sent an Agent Key (`ak-...`). This route family is OAuth-only. | Switch to an OAuth access token. | | Tax request returns `invalid_subject` | `subject` was empty or was neither `personal` nor a legal-entity UUID. | Omit `subject` for all authorized subjects, or pass one valid subject. | | Any command exits `4` or HTTP returns `403` | The credential lacks the required scope, consent, or MoW. | Reauthorize OAuth or ask the owner for a key with the required access. | | `application create` returns `nextSteps.signature` | The Agreement of Coexistence was not pre-accepted. | The owner opens the signature URL once in a browser. Future creates of that residency type can be headless. | | Any command exits `7` or HTTP returns `429` | Per-key rate limit. `verify_rpn` and registry search are capped at 50/minute and 5,000/day. | Respect `Retry-After` and back off. | | Search returns `{ "results": [] }` | Query was too narrow or used punctuation the registry does not index. | Reduce to the most distinctive single word. | | `entity verify` returns `"not_found"` | The RPN string is malformed or unknown. | Treat as terminal; do not retry the same RPN. | ## Polling, Not Webhooks [#polling-not-webhooks] There are no webhook callbacks today. Prefer the CLI watcher: ```bash eprospera --json application watch --timeout 30m ``` Direct HTTP callers should poll `GET /api/v1/legal_entity_applications/{id}` every **30 seconds** for the first 2 minutes, then back off to every **5 minutes**. `Approved` and `Rejected` are terminal — stop polling. ## Machine-Readable Resources [#machine-readable-resources] If your agent has fetch capability, ingest these instead of scraping rendered pages: * [Official CLI](https://github.com/Honduras-Prospera-inc/eprospera-cli) — source repository for the e-Próspera CLI. * [CLI package on npm](https://www.npmjs.com/package/@prospera/eprospera-cli) — current published version and installation metadata. * [CLI releases](https://github.com/Honduras-Prospera-inc/eprospera-cli/releases) — changelog and standalone bundles. * [`/llms.txt`](/llms.txt) — short Markdown index of every doc page, per the [llms.txt standard](https://llmstxt.org/). * [`/llms-full.txt`](/llms-full.txt) — CLI commands, endpoints, scopes, request/response shapes, and conventions in one plain-text file. * [`/openapi.yaml`](/openapi.yaml) — OpenAPI 3.1 spec for direct HTTP clients. ## Where To Go Next [#where-to-go-next] * **Use the CLI:** [CLI](/cli) — install, authenticate, command matrix, exit codes. * **Pick credentials:** [Standard API Keys](/standard-keys) for first-party `sk-` access; [Agent Keys](/agent-keys) for scoped delegation. * **Copy a workflow:** [Agent recipes](/agent-recipes) — CLI and HTTP flows for registry lookup, incorporation, profile reads, and OAuth tax data. * **Build direct HTTP clients:** [Conventions](/conventions) and the reference pages. * **Sign in with e-Próspera:** [OAuth overview](/oauth-overview). * **Read consented entities and taxes:** [Tax and legal-entity data](/tax-and-entity-data).