Skip to main content

​
Making Your First Request

This guide walks you through making your first complete API call, from authentication to retrieving project data.

​
Complete Example

Here’s a complete example that authenticates and retrieves project information:
  • Python
  • curl
import requests

# Configuration
api_url = "https://voyager.lumafield.com"
email = "your-email@company.com"
password = "your-password"

# Step 1: Authenticate
print("Authenticating...")
login_response = requests.post(
    f"{api_url}/api/login",
    json={"email": email, "password": password}
)
login_response.raise_for_status()
token = login_response.json()["token"]
print(f"✓ Authenticated")

# Step 2: Set up headers
headers = {
    "Authorization": f"Token {token}",
    "Content-Type": "application/json"
}

# Step 3: List projects
print("\nFetching projects...")
projects_response = requests.get(
    f"{api_url}/api/v2/projects",
    headers=headers,
    params={"page_size": 10}
)
projects_response.raise_for_status()
projects = projects_response.json()

print(f"✓ Found {projects['count']} total projects")
print(f"  Showing first {len(projects['results'])} projects:\n")

# Step 4: Display project information
for project in projects['results']:
    print(f"  • {project['name']}")
    print(f"    ID: {project['id']}")
    print(f"    Status: {project.get('status', 'N/A')}")
    print()

# Step 5: Get details for first project
if projects['results']:
    first_project_id = projects['results'][0]['id']
    print(f"Getting details for project: {projects['results'][0]['name']}")
    
    project_response = requests.get(
        f"{api_url}/api/v2/projects/{first_project_id}",
        headers=headers
    )
    project_response.raise_for_status()
    project_details = project_response.json()
    
    print(f"  Created: {project_details.get('created_at', 'N/A')}")
    print(f"  Workspace: {project_details.get('workspace', {}).get('name', 'N/A')}")

​
Understanding the Response

​
Projects List Response

{
  "count": 42,
  "next": "https://voyager.lumafield.com/api/v2/projects?page=2",
  "previous": null,
  "results": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Sample Project",
      "status": "active",
      "created_at": "2024-01-15T10:30:00Z",
      "workspace": {
        "id": "workspace-uuid",
        "name": "My Workspace"
      }
    }
  ]
}

​
Project Details Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "Sample Project",
  "status": "active",
  "created_at": "2024-01-15T10:30:00Z",
  "workspace": {
    "id": "workspace-uuid",
    "name": "My Workspace"
  },
  "currentRevision": {
    "document": {
      "objects": {}
    }
  }
}

​
Common Issues

​
Authentication Failed

Error: 401 Unauthorized Solution: Check your email and password, ensure API access is enabled.

​
No Projects Found

Response: Empty results array Solution:
  • Verify you’re authenticated with the correct account
  • Check that you have projects in your Voyager account
  • Try filtering by workspace if applicable

​
Rate Limit Exceeded

Error: 429 Too Many Requests Solution: Add delays between requests, implement exponential backoff.

​
Next Steps