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) → Standard API Keys, Agent Keys, or OAuth (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.
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 <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; `sk-` sees any you represent.
Fetch entity documents	`eprospera --json entity documents <id>`	`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 <id>`	`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 <id> --voucher <code>`	`sk-`, `ak-`	`agent:entity.application.pay`	Voucher must fully cover the invoice.
Create hosted checkout	`eprospera --json --yes application checkout <id> --redirect-url <url> --provider <name>`	`sk-`	—	Agent Key checkout is disabled.
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.
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 <id>`	OAuth	`eprospera:entity.read`	Consent and current representation are both required.
Read consented entity documents	`eprospera --json me legal-entities documents <id>`	OAuth	`eprospera:entity.documents.read`	Consent and current representation are both required.
Show tax obligations	`eprospera --json tax status --subject <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 <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 <filing-id>`	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 <filing-id> --document assessment`	OAuth	`eprospera:person.tax.read` or `eprospera:entity.tax.read`	Output contains confidential financial information.
List referral attribution	`eprospera --json referral list <code>`	`sk-`	—	Agent Keys are not valid for referral reads.
Submit a visitor pass	`eprospera --json --yes visitor-pass create <required flags>`	None	—	All applicant fields and explicit consent are required.

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://stg.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`
`application checkout <id> …`	`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 <id>`	`GET /api/v1/me/legal-entities/{id}`
`me legal-entities documents <id>`	`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 <filing-id>`	`GET /api/v1/me/tax/filings/{filingId}`
`tax download <filing-id> …`	`GET /api/v1/me/tax/filings/{filingId}/documents/{document}`
`referral list <code>`	`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.

Additional REST workflows

Use the filings guide for the complete request and recovery sequences. Use Personal and applicant documents for agreement acceptance, signed-file retrieval, residency matching, and download troubleshooting. No new CLI commands are assumed for these operations.

Action	REST endpoint	Permission and human step
Prepare/read an amendment	`/api/v1/legal_entities/{id}/amendments` and `/{filingId}`	`sk-`, or `ak-` with `agent:entity.filing.create` / `.read`; representative signs at the returned URL
Pay/submit an amendment	`.../amendments/{filingId}/pay/voucher` and `/submit`	`agent:entity.filing.pay`; requires hosted signature and full payment
Request/read/pay a certificate	`.../certificate_requests`, `/{requestId}`, `/{requestId}/pay/voucher`	Corresponding filing scopes; tax contests require registrar review
Read personal documents	`/api/v1/me/natural-person/documents`	OAuth `eprospera:person.documents.read` or `agent:person.documents.read`
Read applicant agreements/policies	`/api/v1/partner/residency_applications/{id}/documents`	`partner:person.application.read`; same integration only

These entity writes use active representation and Agent Key API-created-entity restrictions. OAuth selected-entity consent does not yet authorize filing writes. Preserve IDs on retries; a paid invoice is not proof that review or document generation is complete.

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, or eprospera --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. 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.
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.
You want entities the OAuth user selected during consent. → eprospera --json me legal-entities list, then get or documents with a returned ID.
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.
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 the resident to pay through hosted checkout. → Use application checkout with a standard key. Agent Keys cannot create checkout sessions.
You want to know when an application is approved. → eprospera --json application watch <id> --timeout 30m.
You need referral attribution or a public visitor pass. → Use referral list with a standard key or visitor-pass create without a credential.
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 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 <id>` 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

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.
CLI package on npm — current published version and installation metadata.
CLI releases — changelog and standalone bundles.
/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: Standard API Keys for first-party sk- access; Agent Keys for scoped delegation.
Copy a workflow: Agent recipes — CLI and HTTP flows for registry lookup, incorporation, profile reads, and OAuth tax data.
Build direct HTTP clients: Conventions and the reference pages.
Sign in with e-Próspera: OAuth overview.
Read consented entities and taxes: Tax and legal-entity data.

On this page