# 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) → [Agent Keys](/agent-keys) (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). * **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. | | Fetch entity documents | `eprospera --json entity documents ` | `sk-`, `ak-` | `agent:entity.documents.read` | Same API-created-entity limitation. | | List API-created applications | `eprospera --json application list` | `sk-`, `ak-` | `agent:entity.application.read` | Portal-created applications are invisible to Agent Keys. | | 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. | | Pay with voucher | `eprospera --json --yes application pay --voucher ` | `sk-`, `ak-` | `agent:entity.application.pay` | Voucher must fully cover the invoice. | | 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. | ## 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` | | `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` | OAuth-only entity portfolio endpoints (`/api/v1/me/legal-entities*`) are not covered by Agent Keys. Use the [OAuth overview](/oauth-overview) for consent-based user integrations. ## 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.** Use OAuth and `/api/v1/me/legal-entities/{id}`, or ask the owner to form/manage the entity through the API. 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 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. 8. **You want to know when an application is approved.** → `eprospera --json application watch --timeout 30m`. 9. **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. | Restart through the API/CLI, or have the owner finish it in the portal. | | `entity get ` exits `5` or HTTP returns `404` | Either the entity does not exist, or it was created outside the API and is invisible to Agent Keys. | Use OAuth and `/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. | | Any command exits `4` or HTTP returns `403` | The Agent Key is missing the required scope, or MoW was revoked. | The owner must create a new key with the needed scope. | | `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. * [`/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:** [Agent Keys](/agent-keys) — what they are, who can issue them, scope reference, limitations. * **Copy a workflow:** [Agent recipes](/agent-recipes) — CLI and HTTP flows for registry lookup, automated LLC incorporation, and profile reads. * **Build direct HTTP clients:** [Conventions](/conventions) and the reference pages. * **Sign in with e-Próspera:** [OAuth overview](/oauth-overview).