Skip to content

API_HIVEHUB.md

Latest commit

 

History

History
503 lines (378 loc) · 9.88 KB

API_HIVEHUB.md

File metadata and controls

503 lines (378 loc) · 9.88 KB

HiveHub Cloud API Documentation

Overview

This document describes the HiveHub Cloud API integration for Vectorizer Sync. Note: This API is planned for future implementation and is documented here for reference.

Status

Current Status: Documented only, not implemented

Planned Implementation: Future release

Authentication

OAuth 2.0 Flow

The system SHALL use OAuth 2.0 for authentication with HiveHub Cloud.

Authorization Endpoint

POST https://api.hivehub.cloud/oauth/authorize

Request:

{
  "client_id": "<client_id>",
  "redirect_uri": "vectorizer-sync://oauth/callback",
  "response_type": "code",
  "scope": "workspace:read workspace:write files:read files:write",
  "state": "<random_state>"
}

Response:

  • Redirects to HiveHub login page
  • User authenticates
  • Redirects back to application with authorization code

Token Exchange

POST https://api.hivehub.cloud/oauth/token

Request:

{
  "grant_type": "authorization_code",
  "code": "<authorization_code>",
  "redirect_uri": "vectorizer-sync://oauth/callback",
  "client_id": "<client_id>",
  "client_secret": "<client_secret>"
}

Response:

{
  "access_token": "<access_token>",
  "refresh_token": "<refresh_token>",
  "token_type": "Bearer",
  "expires_in": 3600,
  "scope": "workspace:read workspace:write files:read files:write"
}

Token Refresh

POST https://api.hivehub.cloud/oauth/token

Request:

{
  "grant_type": "refresh_token",
  "refresh_token": "<refresh_token>",
  "client_id": "<client_id>",
  "client_secret": "<client_secret>"
}

Response: Same as token exchange

Token Storage

  • Access tokens stored securely (OS keychain/credential store)
  • Refresh tokens stored securely
  • Tokens automatically refreshed before expiration
  • Tokens cleared on logout

API Base URL

https://api.hivehub.cloud/v1

All API requests MUST include authentication header:

Authorization: Bearer <access_token>

Workspaces

List Workspaces

Get list of user's workspaces.

Endpoint: GET /workspaces

Response:

{
  "workspaces": [
    {
      "id": "ws_abc123",
      "name": "My Workspace",
      "description": "Workspace description",
      "created_at": "2025-12-02T10:30:00.000Z",
      "updated_at": "2025-12-02T15:45:00.000Z",
      "quota_used": 500000000,
      "quota_limit": 1000000000,
      "file_count": 1234
    }
  ]
}

Get Workspace

Get details of a specific workspace.

Endpoint: GET /workspaces/:workspace_id

Response:

{
  "id": "ws_abc123",
  "name": "My Workspace",
  "description": "Workspace description",
  "created_at": "2025-12-02T10:30:00.000Z",
  "updated_at": "2025-12-02T15:45:00.000Z",
  "quota_used": 500000000,
  "quota_limit": 1000000000,
  "file_count": 1234,
  "collections": [
    {
      "id": "col_xyz789",
      "name": "source-code",
      "file_count": 567
    }
  ]
}

Create Workspace

Create a new workspace.

Endpoint: POST /workspaces

Request:

{
  "name": "My New Workspace",
  "description": "Workspace description"
}

Response:

{
  "id": "ws_new123",
  "name": "My New Workspace",
  "description": "Workspace description",
  "created_at": "2025-12-02T16:00:00.000Z",
  "updated_at": "2025-12-02T16:00:00.000Z",
  "quota_used": 0,
  "quota_limit": 1000000000,
  "file_count": 0
}

Update Workspace

Update workspace configuration.

Endpoint: PUT /workspaces/:workspace_id

Request:

{
  "name": "Updated Workspace Name",
  "description": "Updated description"
}

Response: Updated workspace object

Delete Workspace

Delete a workspace (and all its files).

Endpoint: DELETE /workspaces/:workspace_id

Response: 204 No Content

Files

Upload File

Upload a file to a workspace.

Endpoint: POST /workspaces/:workspace_id/files

Request (multipart/form-data):

file: <file content>
path: <relative/path/to/file>
collection: <collection_name>

Response:

{
  "id": "file_abc123",
  "path": "relative/path/to/file",
  "size": 12345,
  "hash": "sha256_hash",
  "uploaded_at": "2025-12-02T16:30:00.000Z",
  "collection_id": "col_xyz789"
}

Update File

Update an existing file.

Endpoint: PUT /workspaces/:workspace_id/files/:file_id

Request (multipart/form-data):

file: <updated file content>

Response: Updated file object

Delete File

Delete a file from workspace.

Endpoint: DELETE /workspaces/:workspace_id/files/:file_id

Response: 204 No Content

List Files

List files in a workspace.

Endpoint: GET /workspaces/:workspace_id/files

Query Parameters:

  • collection: Filter by collection name
  • limit: Maximum number of results (default: 100)
  • offset: Pagination offset

Response:

{
  "files": [
    {
      "id": "file_abc123",
      "path": "relative/path/to/file",
      "size": 12345,
      "hash": "sha256_hash",
      "uploaded_at": "2025-12-02T16:30:00.000Z",
      "updated_at": "2025-12-02T16:30:00.000Z",
      "collection_id": "col_xyz789"
    }
  ],
  "total": 1234,
  "limit": 100,
  "offset": 0
}

Get File

Get file details.

Endpoint: GET /workspaces/:workspace_id/files/:file_id

Response: File object

Account

Get Account Information

Get user account information and quota.

Endpoint: GET /account

Response:

{
  "email": "user@example.com",
  "plan": {
    "type": "free",
    "name": "Free Plan",
    "quota_limit": 1000000000,
    "quota_used": 500000000,
    "quota_percentage": 50
  },
  "workspaces_count": 3,
  "created_at": "2025-01-01T00:00:00.000Z"
}

Get Quota Information

Get detailed quota information.

Endpoint: GET /account/quota

Response:

{
  "quota_limit": 1000000000,
  "quota_used": 500000000,
  "quota_available": 500000000,
  "quota_percentage": 50,
  "warnings": [
    {
      "threshold": 80,
      "message": "You are using 80% of your quota"
    }
  ]
}

Notifications

List Notifications

Get user notifications.

Endpoint: GET /notifications

Query Parameters:

  • unread_only: Return only unread notifications (default: false)
  • limit: Maximum number of results (default: 50)
  • offset: Pagination offset

Response:

{
  "notifications": [
    {
      "id": "notif_abc123",
      "type": "quota_warning",
      "severity": "warning",
      "title": "Quota Warning",
      "message": "You are using 80% of your quota",
      "read": false,
      "action_url": "https://hivehub.cloud/upgrade",
      "created_at": "2025-12-02T15:00:00.000Z"
    }
  ],
  "total": 5,
  "unread_count": 2
}

Mark Notification as Read

Mark a notification as read.

Endpoint: PUT /notifications/:notification_id/read

Response: 204 No Content

Mark All as Read

Mark all notifications as read.

Endpoint: PUT /notifications/read-all

Response: 204 No Content

Error Handling

Error Response Format

All API errors follow this format:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {
      "field": "additional error details"
    }
  }
}

HTTP Status Codes

  • 200 OK: Successful request
  • 201 Created: Resource created successfully
  • 204 No Content: Successful request with no response body
  • 400 Bad Request: Invalid request parameters
  • 401 Unauthorized: Authentication required or invalid token
  • 403 Forbidden: Insufficient permissions
  • 404 Not Found: Resource not found
  • 409 Conflict: Resource conflict (e.g., quota exceeded)
  • 429 Too Many Requests: Rate limit exceeded
  • 500 Internal Server Error: Server error
  • 503 Service Unavailable: Service temporarily unavailable

Error Codes

  • AUTH_REQUIRED: Authentication required
  • AUTH_INVALID: Invalid authentication token
  • AUTH_EXPIRED: Authentication token expired
  • QUOTA_EXCEEDED: Quota limit exceeded
  • QUOTA_WARNING: Approaching quota limit
  • FILE_TOO_LARGE: File exceeds size limit
  • FILE_INVALID: Invalid file format
  • WORKSPACE_NOT_FOUND: Workspace not found
  • FILE_NOT_FOUND: File not found
  • RATE_LIMIT_EXCEEDED: Rate limit exceeded
  • SERVER_ERROR: Internal server error

Rate Limiting

API requests are rate-limited:

  • Default: 100 requests per minute per user
  • File Uploads: 10 uploads per minute per workspace
  • Rate Limit Headers:
    • X-RateLimit-Limit: Maximum requests allowed
    • X-RateLimit-Remaining: Remaining requests
    • X-RateLimit-Reset: When rate limit resets (Unix timestamp)

When rate limit is exceeded, the API returns 429 Too Many Requests.

Retry Logic

The client SHALL implement exponential backoff for:

  • Network errors
  • 429 Too Many Requests responses
  • 503 Service Unavailable responses

Retry Strategy:

  1. Initial delay: 1 second
  2. Maximum delay: 60 seconds
  3. Maximum retries: 5
  4. Exponential backoff: delay = min(initial_delay * 2^retry_count, max_delay)

Webhooks (Future)

Webhooks may be implemented in the future for:

  • File upload completion
  • Quota warnings
  • Workspace updates
  • Account changes

Security

  1. HTTPS Only: All API communications use HTTPS
  2. Token Security: Tokens stored securely (OS keychain)
  3. Token Refresh: Automatic token refresh before expiration
  4. Request Signing: Optional request signing for additional security (future)

Implementation Notes

Request Timeout

  • Default timeout: 30 seconds
  • File upload timeout: 5 minutes
  • Configurable per request type

File Upload

  • Maximum file size: Based on plan quota
  • Supported formats: All text-based files
  • Binary files: Excluded by default
  • Chunked upload: For large files (future)

Synchronization Strategy

  1. Initial Sync: Upload all files
  2. Incremental Sync: Upload only changed files (based on hash)
  3. Conflict Resolution: Last-write-wins (configurable)
  4. Batch Operations: Batch file operations for efficiency