Skills for AI 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.
TL;DR — what an agent must internalize before the first call
- Use the CLI first when shell access is available:
eprospera --json --yes <group> <command>. - Docs, in order: CLI (install, auth, exit codes) → Agent Keys (credentials & scopes) → Conventions (HTTP rules) → this page (capabilities & dead ends) → Agent recipes (copy-paste workflows).
- Every Agent Key request is scope-checked. CLI exit code
4or HTTP403means the key is missing the scope, not that the resource is absent. - A
404/ CLI exit code5from 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. - There are no webhooks. Use
eprospera application watch <id> --timeout 30mor poll the direct API — see Polling, not webhooks.
Invocation Rules
Prefer this shape for automation:
eprospera --json --yes <group> <command>- Parse stdout as JSON. Treat stderr as diagnostics.
- Use
--rawwhen compact single-line JSON is better. - Use
--fields id,statusId,nameto reduce read responses. - Use
--dry-runbefore write commands while constructing request files. - Put credentials in
--api-key,EPROSPERA_API_KEY, orauth login; never echo tokens. - Use
EPROSPERA_ENV=stagingfor staging checks. - Use direct HTTP only when the CLI does not cover the task or you are implementing your own client.
CLI Capability Matrix
| I want to… | Run | Credentials | Required scope | Common dead-end |
|---|---|---|---|---|
| Confirm an RPN exists | eprospera --json entity verify <rpn> | sk-, ak- | agent:verify_rpn | RPN must be 14 digits starting with 8 or 9. |
| Search the registry | eprospera --json entity search "<query>" | sk-, ak- | agent:registry.search | Empty results are not a bug; broaden or simplify the query. |
| Fetch one legal entity | eprospera --json entity get <id> | sk-, ak- | agent:entity.read | Agent Keys see only API-created entities. |
| Fetch entity documents | eprospera --json entity documents <id> | 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 <id> --voucher <code> | sk-, ak- | agent:entity.application.pay | Voucher must fully cover the invoice. |
| Watch for approval | eprospera --json application watch <id> --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
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 <rpn> | POST /api/v1/verify_rpn |
entity search "<query>" | POST /api/v1/registries/legal_entities/search |
entity get <id> | GET /api/v1/legal_entities/{id} |
entity documents <id> | 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 <id> / application watch <id> | GET /api/v1/legal_entity_applications/{id} |
application pay <id> --voucher <code> | 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 for consent-based user integrations.
Decision Tree — Pick the Right Command
Walk this top-down. Stop at the first row that matches your goal.
-
You need to store or inspect credentials. →
eprospera auth login,eprospera --json auth whoami, oreprospera --yes auth logout. -
You have an RPN string and want to know if it is real and active. →
eprospera --json entity verify <rpn>. -
You have a human-readable name or partial RPN and want to find the entity. →
eprospera --json entity search "<query>". If results are empty, broaden the query — do not retry the same input. -
You have a legal-entity ID that your own agent created earlier. →
eprospera --json entity get <id>. -
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. -
You want data about the human who owns the Agent Key or OAuth credential. →
eprospera --json me profile,me residency, orme id-verificationwith the matching scope. -
You want to incorporate a new LLC. → See Recipe 2. Confirm MoW, pre-accepted AOC, and a fully covering voucher before the agent starts.
-
You want to know when an application is approved. →
eprospera --json application watch <id> --timeout 30m. -
You need exact wire-level request and response shapes. → Use the direct HTTP reference pages.
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 <id> 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
There are no webhook callbacks today. Prefer the CLI watcher:
eprospera --json application watch <application-id> --timeout 30mDirect 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
If your agent has fetch capability, ingest these instead of scraping rendered pages:
- Official CLI — source repository for the e-Próspera CLI.
/llms.txt— short Markdown index of every doc page, per the llms.txt standard./llms-full.txt— CLI commands, endpoints, scopes, request/response shapes, and conventions in one plain-text file./openapi.yaml— OpenAPI 3.1 spec for direct HTTP clients.
Where To Go Next
- Use the CLI: CLI — install, authenticate, command matrix, exit codes.
- Pick credentials: Agent Keys — what they are, who can issue them, scope reference, limitations.
- Copy a workflow: Agent recipes — CLI and HTTP flows for registry lookup, automated LLC incorporation, and profile reads.
- Build direct HTTP clients: Conventions and the reference pages.
- Sign in with e-Próspera: OAuth overview.
Agent recipes
End-to-end Agent Key workflows you can copy, paste, and run. The CLI path is recommended when your runtime can execute shell commands; direct HTTP examples are included for custom clients and environments where the CLI is not available.
Incorporating an entity
This guide walks through the CLI and direct API flow for incorporating an LLC in Próspera.