Getting Started

The CoLoop API enables data collection platform (DCP) developers to integrate CoLoop’s AI content analysis capabilities into their applications. This guide will help you get started with the API.

​

API Information

• Base URL: https://api.coloop.ai
• Current Version: v1
• API Documentation: Complete OpenAPI documentation available at https://api.coloop.ai/docs
• API Status: https://status.coloop.ai

All API requests should be made to: https://api.coloop.ai/v1/

​

Authentication

CoLoop uses OAuth 2.0 for authentication, supporting both private (server-side) and public (client-side) applications. After completing the OAuth flow, you’ll receive a JWT token to use for API requests.

​

Security Headers

All API requests require a Bearer token:

Authorization: Bearer your_access_token

​

Core Resources

​

Projects

Projects are the main organizational unit in CoLoop. They contain resources (like transcripts and media) that you want to analyze.

​

List Projects

GET /v1/projects/

Example response:

{
  "projects": [
    {
      "id": "proj_123",
      "name": "Customer Interview Analysis",
      "description": "Q4 customer feedback analysis",
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z",
      "ownerId": "user_123",
      "organizationId": "org_123",
      "keywords": ["feedback", "support"],
      "embeddingModel": "text_embedding_3_small"
    }
  ]
}

​

Create Project

POST /v1/projects/
Content-Type: application/json

{
  "name": "New Research Project",
  "description": "Analysis of user interviews",
  "organization_id": "org_123"
}

​

Resources

Resources are the actual content you want to analyze. The API supports several types of resources:

1. Transcripts
2. Media files
3. Combined transcript and media
4. Research activities with responses

​

Add Resource to Project

POST /v1/projects/{projectId}/resources/
Content-Type: application/json

{
  "external_id": "interview_123",
  "name": "Customer Interview #1",
  "data": {
    "transcript": {
      "speakers": [
        {
          "id": "speaker_1",
          "name": "Interviewer",
          "role": "moderator"
        },
        {
          "id": "speaker_2",
          "name": "Participant",
          "role": "participant"
        }
      ],
      "speech_turns": [
        {
          "speaker_id": "speaker_1",
          "content": "Can you tell me about your experience?"
        }
      ]
    }
  }
}

​

Common Patterns

​

Resource Types

The API supports different types of analysis content:

1. Interview Transcripts

   • Structured conversation data
   • Speaker identification
   • Timestamped speech turns

2. Research Activities

   • Multi-respondent studies
   • Task-based responses
   • Mixed media support (text, audio, video, images)

3. Media Files

   • Audio recordings
   • Video content
   • Images with captions

​

Storage Considerations

• Projects can specify a storageRegion (us, uk, eu)
• Media files require a two-step process:
  1. Create resource and receive upload URLs
  2. Upload media to provided URLs

​

Support

During the Alpha phase, contact the CoLoop team for:

• OAuth application setup
• API access questions
• Integration support
• Feature requests

​

Next Steps

1. Set up your OAuth application with CoLoop
2. Create your first project
3. Add some resources for analysis
4. Explore the detailed API documentation at https://api.coloop.ai/docs/