Pilot Onboarding

Tip

This guide is for platform administrators onboarding a new tenant. If you’re a developer building data products on an existing tenant, start with the Quickstart.

Prerequisites

• Admin access to Akili API (admin role via SSO)
• Tenant details: slug, display name, pricing tier
• Source database connection details (host, port, credentials)

Onboarding Steps

1. Create tenant

   curl -X POST https://api.akili.systems/api/v1/tenants \
     -H "Authorization: Bearer $ADMIN_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "slug": "acme-corp",
       "display_name": "Acme Corporation",
       "tier": "standard"
     }'

   This automatically provisions:

   • Structured store schema with RLS policies
   • S3 storage bucket (object store)
   • Event bus topics
   • Analytics engine catalog (lakehouse federation)
   • Ingestion connector destination (lakehouse, tenant-namespaced)

   Wait for the response — provisioning takes 10-30 seconds.

2. Create SSO users

   In the SSO admin panel (https://auth.akili.systems/if/admin/):

   1. Create user accounts for the tenant’s team
   2. Assign users to the appropriate groups:
      • akili-developers — can create and deploy data products
      • akili-viewers — read-only access to data products
   3. Set the tenant_id attribute on the user’s group (for SSO-to-tenant mapping)

3. Register external data sources

   # Register a PostgreSQL source
   curl -X POST https://api.akili.systems/api/v1/connections \
     -H "Authorization: Bearer $TENANT_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "production_db",
       "connector_type": "postgresql",
       "config_encrypted": "{\"host\":\"db.acme.com\",\"port\":5432,\"database\":\"production\",\"user\":\"readonly\",\"password\":\"...\",\"ssl_mode\":\"require\"}"
     }'

   Test and discover:

   # Test the connection
   curl -X POST https://api.akili.systems/api/v1/connections/{connection_id}/test \
     -H "Authorization: Bearer $TENANT_TOKEN"
   
   # Discover available tables
   curl https://api.akili.systems/api/v1/connections/production_db/discover \
     -H "Authorization: Bearer $TENANT_TOKEN"

4. Create a data product

   Write the 6 YAML manifest files. See the Sales Analytics Example for a complete working set.

   Required files:

   File	Purpose
   product.yaml	Name, namespace, archetype, description
   inputs.yaml	Source connections and tables
   output.yaml	Output format, partitioning, retention
   quality.yaml	Data quality checks
   serving.yaml	How the data should be served
   compute.yaml	Compute requirements

   Register, upload, and deploy:

   # Register the product
   curl -X POST https://api.akili.systems/api/v1/products \
     -H "Authorization: Bearer $TENANT_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "daily_order_summary",
       "namespace": "sales",
       "archetype": "aggregate",
       "description": "Daily aggregated order metrics by region"
     }'
   
   # Upload manifests
   curl -X POST https://api.akili.systems/api/v1/products/{product_id}/manifests \
     -H "Authorization: Bearer $TENANT_TOKEN" \
     -F "product=@product.yaml" \
     -F "inputs=@inputs.yaml" \
     -F "output=@output.yaml" \
     -F "quality=@quality.yaml" \
     -F "serving=@serving.yaml" \
     -F "compute=@compute.yaml"
   
   # Deploy (dry run first)
   curl -X POST https://api.akili.systems/api/v1/products/{product_id}/deploy \
     -H "Authorization: Bearer $TENANT_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"version": "1.0.0", "dry_run": true}'
   
   # Deploy for real
   curl -X POST https://api.akili.systems/api/v1/products/{product_id}/deploy \
     -H "Authorization: Bearer $TENANT_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{"version": "1.0.0", "dry_run": false}'

5. Trigger ingestion

   # Initial sync
   curl -X POST https://api.akili.systems/api/v1/connections/{connection_id}/sync \
     -H "Authorization: Bearer $TENANT_TOKEN"
   
   # Check sync status
   curl https://api.akili.systems/api/v1/ingestion?tenant_id={tenant_id} \
     -H "Authorization: Bearer $TENANT_TOKEN"

6. Query data

   curl -X POST https://api.akili.systems/api/v1/query \
     -H "Authorization: Bearer $TENANT_TOKEN" \
     -H "Content-Type: application/json" \
     -d '{
       "sql": "SELECT * FROM sales.daily_order_summary ORDER BY date DESC LIMIT 10"
     }'

7. Monitor

   • Grafana: https://grafana.akili.systems — login with SSO
   • Data quality: Check quality scores in the product detail view
   • Pipeline status: Check ingestion state via API

Troubleshooting

Issue	Resolution
Connection test fails	Verify network access from cluster to source DB. Check firewall rules.
Ingestion stuck in “running”	Check ingestion connector sync job status. Logs in the ingestion namespace.
Quality checks failing	Review check SQL in quality.yaml. Check source data freshness.
Deploy fails	Run with dry_run: true first. Check manifest validation errors.
Cross-tenant data visible	Verify RLS policies. Check SET LOCAL app.tenant_id in logs.

Resource Limits

Tier	Products	Connections	Concurrent Executions	Storage
Free	5	3	2	10 GB
Standard	50	20	5	100 GB
Enterprise	Unlimited	Unlimited	20	1 TB

Next Steps

• Sales Analytics Example — complete working data product
• Write Manifests — field-by-field manifest reference
• End-to-End Tutorial — full declare, deploy, query lifecycle