Get Started

This guide will walk you through setting up authentication and making your first API request to Yeino.

Authentication

All API requests require authentication using an API key. API keys are organization-scoped and provide secure access to your Yeino data.

API Key Format

API keys follow this format:


yno_live_abc123def456...

The yno_live_ prefix indicates a live (production) API key. Test keys (if available) would use a different prefix.

Including Your API Key

Include your API key in the x-api-key header with every request:


curl -H "x-api-key: yno_live_your_api_key_here" \
  https://api.yeino.com/v2/projects/{projectId}

Getting Your API Key

Navigate to Organization Settings

Log in to your Yeino dashboard
Select your organization from the dropdown
Go to Settings → API Keys

Create a New API Key

Click Create New Key
Enter a descriptive name (e.g., “Production API”, “Development Script”)
Select a permission level:
- Read Only - Can retrieve data (GET requests only)
- Read & Write - Full access (GET, POST, etc.)
Click Create Key

Copy and Store Your Key

⚠️ Important: You’ll only see the full API key once when it’s created. Make sure to copy it immediately and store it securely.

The API key will be displayed in a dialog. Copy it to a secure location:

Environment variables (recommended)
Secret management service (AWS Secrets Manager, HashiCorp Vault, etc.)
Secure password manager

Never commit API keys to version control or share them publicly.

API Key Permissions

API keys have two permission levels that control what actions you can perform:

Permission	Access	Use Case
`read`	Read-only access. Can use GET endpoints only.	Monitoring dashboards, reporting tools, read-only integrations
`read_write`	Full access. Can use all endpoints (GET, POST, etc.).	Automated uploads, data synchronization, full integrations

Permission Requirements by Endpoint

Read-only endpoints (require read permission):

GET /v2/projects/{projectId} - Get project information
GET /v2/recordings/{recordingId} - Get recording details
GET /v2/recordings/{recordingId}/status - Check recording status
GET /v2/projects/{projectId}/insights - List insights

Write endpoints (require read_write permission):

POST /v2/projects/{projectId}/recordings - Initiate recording upload
POST /v2/recordings/{recordingId}/complete - Complete recording upload

Rate Limits

Rate limits are based on your organization’s billing plan:

Plan	Requests per minute
Free	60
Basic	300
Pro	1000

When you exceed the rate limit, you’ll receive a 429 Too Many Requests response:


{
  "statusCode": 429,
  "message": "Rate limit exceeded. Please try again later.",
  "error": "Too Many Requests"
}

Making Your First Request

Let’s make a simple request to retrieve project information:


curl -X GET "https://api.yeino.com/v2/projects/YOUR_PROJECT_ID" \
  -H "x-api-key: yno_live_your_api_key_here"

Response:


{
  "id": "507f1f77bcf86cd799439011",
  "organizationId": "507f1f77bcf86cd799439012",
  "name": "User Research Q1 2025",
  "description": "User interviews for the new checkout flow",
  "category": "user_research",
  "stats": {
    "recordingsCount": 15,
    "insightsCount": 42,
    "chatsCount": 5
  },
  "createdAt": "2024-01-15T10:30:00.000Z"
}

Error Responses

All endpoints return errors in a consistent format:


{
  "statusCode": 401,
  "message": "Invalid API key.",
  "error": "Unauthorized"
}

Common Error Codes

Status	Description	Solution
400	Bad Request - Invalid parameters	Check your request body and parameters
401	Unauthorized - Invalid or missing API key	Verify your API key is correct and included in the `x-api-key` header
403	Forbidden - Insufficient permissions	Ensure your API key has the required permission level (`read` or `read_write`)
404	Not Found - Resource doesn’t exist	Verify the resource ID (project, recording, etc.) is correct
429	Too Many Requests - Rate limit exceeded	Wait before making more requests or upgrade your plan
500	Internal Server Error	Contact support if the issue persists

Security Best Practices

Never commit API keys to version control
Use environment variables for key storage
Rotate keys periodically for security
Use the minimum required permission level - prefer read when possible
Monitor key usage through the dashboard
Revoke unused keys immediately
Use different keys for different environments (production, staging, development)

Managing API Keys

You can manage your API keys through the Yeino dashboard:

View all keys - See all active API keys for your organization
Monitor usage - Track request counts and last used timestamps
Revoke keys - Immediately revoke access for compromised or unused keys
Check limits - View your current key count (maximum 10 per organization)

Next Steps

Now that you understand authentication, explore the API:

Projects - Retrieve project information
Recordings - Upload and manage recordings
Insights - Access AI-generated insights
Complete Example - See a full end-to-end integration workflow