# CIDIF.TECH — External Agent API
# Base URL: https://www.cidif.tech

## Auth
- Authentication: notlogin Verifiable Credential (VC) in body. No session cookie needed.
- Get credential at: /dashboard/agent/connect

## Scopes
- `read`:  read-only, no money/legal fields
- `write`: full read + write access (all fields, including money/legal)
- `admin`: same as `write` (reserved for future settings access)

## POST /api/agent/external/apply
Write actions. Body: { vcJson: <VC>, actions: [...] }

Actions:
  create_company  → { type: "create_company", data: { name, document_type, document_number, country, incorporation_date, business_activities[], direccion, estado, legal_name, tax_id, team_members[{name,role,email}] } }
  update_company  → { type: "update_company", companyId: "<uuid>", field: "<key>", value: <any> }
  create_project  → { type: "create_project", data: { name, description, industry, stage, team_size, founded_date, country, city, address, contact_name, contact_email, contact_phone, contact_position, website_url, linkedin_url, problem_statement, target_market, value_proposition, business_model, competitive_advantages, technology_description, product_status, monthly_users, monthly_revenue, customer_count, annual_revenue, funding_seeking, legal_name, tax_id, legal_entity_type } }
  update_project  → { type: "update_project", projectId: "<uuid>", field: "<key>", value: <any>, reason?: "<why>" }
## save_answer action
  { type: "save_answer", applicationId: "<uuid>", sectionKey: "<string>", content: "<text>" }
  sectionKey is a STRING (e.g. "text_ingrese_el_titulo"), NOT a UUID.
  To discover sectionKey values, query get_application → sections[].sectionKey.
  For template keys (fund questions), query get_fund → sections (use those as sectionKey).

Scope-gated fields (require `write` or `admin`; `read` is blocked): funding_received, funding_seeking, monthly_revenue, annual_revenue, tax_id, legal_name, legal_entity_type, document_number, team_members

## POST /api/agent/external/query
Read actions. Body: { vcJson: <VC>, query: { type, ... } }

Query types:
  list_projects    → { type: "list_projects" }
  get_project      → { type: "get_project", id: "<uuid>" }
  list_companies    → { type: "list_companies" }
  get_canonical_profile → { type: "get_canonical_profile" }
  list_applications → { type: "list_applications", projectId?: "<uuid>" }
  get_application   → { type: "get_application", applicationId: "<uuid>" }  // returns sections with id + sectionKey
  list_funds       → { type: "list_funds" }
  get_fund          → { type: "get_fund", id: "<uuid>" }

## POST /api/agent/external/draft
Portal form field resolution. Body: { vcJson: <VC>, fields: [{ label, type?, projectId? }] }
Resolves via canonical → memory → AI cascade. Never hallucinates hard data.

## POST /api/agent/external/spec
Returns full OpenAPI-like field catalogue (enums, required scopes).

## Enums
- industry: technology, health, fintech, agritech, energy, education, ecommerce, logistics, manufacturing, food, environment, other
- stage: idea, mvp, early_revenue, growth, scale
- country: CL, PE, MX, CO, AR, US, EU
- document_type: RUT, RUC, NIT, CUIT, OTHER
- currency: CLP, USD, EUR, PEN, MXN, COP, ARS
- product_status: idea, prototype, mvp, beta, launched
- legal_entity_type: spa, sa, ltda, eirl, corporation, llc, other
- project_role: ceo, cto, coo, cfo, engineering_lead, product_lead, marketing_lead, sales_lead, operations, advisor, other
- dedication: full_time, part_time
- gender: male, female, non_binary, other, prefer_not_to_say

## Security
- VC binds verified email to CIDIF account
- All writes scoped to the mapped user_id
- Column allowlisting per scope (read/write/admin)
- Audit trail: every action logged to external_agent_audit
- Money/legal fields require admin scope