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 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.
• There are no webhooks. Use eprospera application watch <id> --timeout 30m or 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 --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

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.

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 <rpn>.

3. 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.

4. You have a legal-entity ID that your own agent created earlier. → eprospera --json entity get <id>.

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. 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 <id> --timeout 30m.

9. 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 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

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.