Layi Docs

API Integration

Call installed Layi service-template operations directly from buyer backend systems.

Last updated: June 2026

Direct HTTP access for installed apps

Use the API integration option when your backend needs to discover or run actions from installed apps such as Receptionist, HR/payroll, or AI Data. The API is a thin customer-safe adapter over the canonical service-template contract, so it shares tenant scoping, approval gates, advisory compliance checks, and audit events with the dashboard.

If you prefer Python helpers, use the SDK. If a frontier agent or copilot should discover callable tools, use MCP Integration.

Backend systems
Submit work from internal platforms, data pipelines, CRMs, or workflow engines.
Frontend-equivalent actions
Run allowed installed-service actions through the same runtime path the app workspace uses.
Auditable by default
External attempts are recorded with actor, source, action key, status, request context, and compliance results when available.

Authentication

Customer API integrations use X-API-Key with the customer key pair generated in Org Manager. Do not use internal admin API keys for customer integrations.

Required header

X-API-Key: pk_xxx:sk_xxxContent-Type: application/json

Installed-service endpoints

GET/services/{service_id}/integration-contract

Discover allowed installed-service actions, schemas, access classes, and surfaces.

POST/services/{service_id}/integration-actions/{action_key}/plan

Preview an action before execution and inspect approval/compliance expectations.

POST/services/{service_id}/integration-actions/{action_key}/execute

Execute an allowed action through the same service-template runtime used by the dashboard.

POST/services/{service_id}/a2a/tasks

Optional async task bridge for partner orchestration with callback and polling fallback.

1. Discover the contract

Start by discovering the installed service contract. The contract tells your integration which actions exist, which surfaces are enabled, and which actions require approval.

curl -s   -H "X-API-Key: pk_xxx:sk_xxx"   https://agent.layi.ai/services/svc_123/integration-contract

2. Plan, then execute

Plan first when wiring a new action. Execute only after your service has checked access class, approval requirements, and the buyer’s policy.

curl -s   -H "X-API-Key: pk_xxx:sk_xxx"   -H "Content-Type: application/json"   -d '{"params":{"tier":"senior"}}'   https://agent.layi.ai/services/svc_123/integration-actions/talent.list_volume_tier/plancurl -s   -H "X-API-Key: pk_xxx:sk_xxx"   -H "Content-Type: application/json"   -d '{"params":{"tier":"senior"}}'   https://agent.layi.ai/services/svc_123/integration-actions/talent.list_volume_tier/execute

Approval-gated actions

Some write, admin, or export actions require explicit approval before execution. Send approved_execution and an approval note only after your own policy has approved the action.

curl -s   -H "X-API-Key: pk_xxx:sk_xxx"   -H "Content-Type: application/json"   -d '{    "params": {"pay_period":"2026-06"},    "approved_execution": true,    "approval_note": "Approved by payroll owner in ticket PAY-1024"  }'   https://agent.layi.ai/services/svc_hr/integration-actions/hr.run_payroll/execute

Compliance payloads on execution

API executions inherit the organization business profile before they run. The runtime combines org-level industry, region, compliance regimes, and data classes with the installed template requirements and the specific action payload. The response can include a safe compliance object so your system can inspect the result programmatically.

Org settings
Business profile settings establish the baseline for the authenticated organization.
Action context
The service id, action key, and params determine the specific compliance scope for that execution.
Audit evidence
Compliance flags and audit-required outcomes are preserved in service action history.
{  "status": "succeeded",  "service_id": "svc_hr",  "action_key": "hr.run_payroll",  "output": {    "summary": "Payroll run prepared for approval review"  },  "compliance": {    "passed": false,    "flagged": true,    "violations": ["approval_required_for_payroll_admin_action"],    "audit_required": true,    "merged_envelope": {      "regimes": ["GDPR", "PCI-DSS"],      "data_classes": ["PII", "PCI"]    }  },  "audit_events": [    {"event_type": "compliance_review", "status": "flagged"}  ]}

Compliance fields are advisory and auditable. They are designed for workflow enforcement, review, and evidence collection; they are not a certification claim.

Service examples

  • Receptionist

    Discover appointment and message actions, then call safe read/list actions or approved write actions such as appointment creation.

  • HR/payroll

    Use tenant-scoped staff, leave, benefits, or payroll-adjacent actions. Treat payroll and compensation actions as approval-gated.

  • AI Data

    Submit or inspect expert operations, quality audit, rubric, identity, Sybil, or exclusion workflows as the installed template permits.

Safety boundaries

API responses intentionally omit raw provider bindings, credential-bearing setup metadata, and internal routing details. Compliance checks are advisory and auditable; do not describe them as certification.

MCP Integration

Expose installed-service operations as allowlisted tools for frontier agents and copilots.