API Documentation

Comprehensive API reference for integrating with Octocular Lab's platform. Build powerful integrations with our RESTful API.

Getting Started

Welcome to the Octocular Lab API documentation. This guide will help you get started with integrating our API into your application.

Base URL

https://octocular.io/api/v1

Quick Start

All API requests must include your API key in the header:

curl https://octocular.io/api/v1/endpoint \
  -H "Authorization: Bearer {auth_token}" \
  -H "Content-Type: application/json"

Authentication

The Octocular Lab API uses API keys to authenticate requests. You can view and manage your API keys in your account settings.

Using Your API Key

Include your API key in the Authorization header of every request:

curl https://octocular.io/api/v1/endpoint \
  -H "Authorization: Bearer {auth_token}"

API Endpoints

Explore our API endpoints. Detailed documentation for each endpoint will be available here.

POST/api/v1/rooms

Create new interview rooms

Create a new interview room for conducting technical interviews with candidates.

Request Example

curl -X POST "https://octocular.io/api/v1/rooms" \
  -H "Authorization: Bearer {auth_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "user": {
        "id": "{user_id}",
        "organization_id": "{organization_id}"
    },
    "candidate_email": "{candidate_email}",
    "settings": {
        "enable_chat_assistant": true
    },
    "scheduled_time": "2026-01-01T10:00:00.000Z"
  }'

Request Body Parameters

user(object, required)

id - User ID
organization_id - Organization ID

candidate_email(string, required)

Email address of the candidate

settings(object, optional)

enable_chat_assistant - Enable chat assistant feature

scheduled_time(string, optional)

ISO 8601 formatted datetime for scheduled interview

Response Example

{
  "success": true,
  "data": {
    "room_id": "{room_id}",
    "session_link": "{room_url}",
    "candidate_email": "{candidate_email}",
    "scheduled_time": "2026-01-01T10:00:00+00:00",
    "expires_at": null,
    "created_at": "2025-12-04T10:00:00+00:00",
    "status": "active",
    "settings": {
      "enable_chat_assistant": true
    }
  }
}

GET/api/v1/rooms

List all interview rooms

Retrieve a list of all interview rooms with pagination support.

Request Example

curl -X GET "https://octocular.io/api/v1/rooms" \
  -H "Authorization: Bearer {auth_token}"

Response Example

{
  "success": true,
  "data": [
    {
      "room_id": "{room_id_1}",
      "candidate_email": "{candidate_email}",
      "status": "active"
    },
    {
      "room_id": "{room_id_2}",
      "candidate_email": "{candidate_email}",
      "status": "active"
    },
    {
      "room_id": "{room_id_3}",
      "candidate_email": "{candidate_email}",
      "status": "active"
    }
  ],
  "pagination": {
    "limit": 3,
    "offset": 0,
    "total": 3
  }
}

Response Fields

data(array)

Array of interview room objects

room_id - Unique identifier for the room
candidate_email - Email address of the candidate
status - Current status of the room (e.g., "active")

pagination(object)

limit - Number of items per page
offset - Number of items skipped
total - Total number of items available

GET/api/v1/rooms/{room_id}

Get room information by id

Retrieve detailed information about a specific interview room by its ID.

Path Parameters

room_id(string, required)

The unique identifier of the interview room

Request Example

curl -X GET "https://octocular.io/api/v1/rooms/{room_id}" \
  -H "Authorization: Bearer {auth_token}"

Response Example

{
  "success": true,
  "data": {
    "room_id": "{room_id}",
    "session_link": "{room_url}",
    "candidate_email": "{candidate_email}",
    "scheduled_time": "2026-01-01T10:00:00+00:00",
    "expires_at": null,
    "created_at": "2025-12-05T10:00:00+00:00",
    "status": "active",
    "settings": {
      "enable_chat_assistant": true
    }
  }
}

DELETE/api/v1/rooms/{room_id}

Delete an interview room by id

Delete a specific interview room by its ID. This action is permanent and cannot be undone.

Path Parameters

room_id(string, required)

The unique identifier of the interview room to delete

Request Example

curl -X DELETE "https://octocular.io/api/v1/rooms/{room_id}" \
  -H "Authorization: Bearer {auth_token}"

Response Example

{
  "success": true,
  "message": "Room deleted successfully",
  "data": {
    "room_id": "abc12345"
  }
}