Opportunities API

The Opportunities API provides comprehensive endpoints for managing job offers, project requests, and collaboration opportunities within the Ring platform. It supports full CRUD operations, file uploads, search functionality, and role-based access control.

Base URL

https://ring.platform/api/opportunities

Authentication

Most endpoints require authentication via NextAuth.js session or API key. Role-based access control is enforced based on user permissions.

Endpoints Overview

GET /api/opportunities - List opportunities with filtering and pagination
GET /api/opportunities/[id] - Get specific opportunity details
POST /api/opportunities/create - Create new opportunity
PUT /api/opportunities/update - Update existing opportunity
DELETE /api/opportunities/delete/[id] - Delete opportunity
POST /api/opportunities/upload - Upload opportunity attachments
GET /api/confidential/opportunities - Access confidential opportunities

Core Endpoints

GET /api/opportunities

Retrieve a paginated list of opportunities with advanced filtering and search capabilities.

Method: GET
Authentication: Optional (affects visibility)
Rate Limit: 100 requests per minute

Query Parameters

Parameter	Type	Required	Description
`page`	number	No	Page number for pagination (default: 1)
`limit`	number	No	Items per page (default: 10, max: 50)
`category`	string	No	Filter by opportunity category
`type`	string	No	Filter by type (job, project, collaboration)
`budget_min`	number	No	Minimum budget filter
`budget_max`	number	No	Maximum budget filter
`location`	string	No	Filter by location
`remote`	boolean	No	Filter for remote opportunities
`search`	string	No	Search in title and description
`entity_id`	string	No	Filter by posting entity
`sort`	string	No	Sort field (created_at, budget, title, views)
`order`	string	No	Sort order (asc, desc)
`status`	string	No	Filter by status (active, expired, closed)

Example Request

GET /api/opportunities?category=Software%20Development&remote=true&limit=20&page=1

Response Schema

{
  "success": true,
  "data": {
    "opportunities": [
      {
        "id": "opp_123456",
        "title": "Senior Full-Stack Developer",
        "description": "We are looking for an experienced full-stack developer...",
        "short_description": "Senior developer position with modern tech stack",
        "category": "Software Development",
        "type": "job",
        "budget": {
          "min": 3000,
          "max": 5000,
          "currency": "USD",
          "per": "month"
        },
        "location": {
          "city": "Kyiv",
          "country": "Ukraine",
          "remote": true,
          "timezone": "Europe/Kiev"
        },
        "requirements": [
          "5+ years of experience",
          "React, Node.js proficiency",
          "English B2+"
        ],
        "benefits": [
          "Flexible schedule",
          "Health insurance",
          "Professional development"
        ],
        "entity": {
          "id": "entity_456",
          "name": "TechCorp Ukraine",
          "logo": "https://storage.com/logos/techcorp.png"
        },
        "tags": ["react", "nodejs", "typescript", "remote"],
        "status": "active",
        "visibility": "public",
        "created_at": "2024-01-15T10:00:00Z",
        "updated_at": "2024-01-16T14:30:00Z",
        "expires_at": "2024-03-15T23:59:59Z",
        "views": 245,
        "applications": 12,
        "is_featured": false
      }
    ],
    "pagination": {
      "current_page": 1,
      "total_pages": 15,
      "total_items": 147,
      "per_page": 10,
      "has_next": true,
      "has_prev": false
    },
    "filters": {
      "categories": ["Software Development", "Design", "Marketing"],
      "types": ["job", "project", "collaboration"],
      "locations": ["Kyiv", "Lviv", "Kharkiv", "Remote"]
    }
  }
}

Error Responses

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMETERS",
    "message": "Invalid query parameters provided",
    "details": {
      "field": "limit",
      "reason": "Must be between 1 and 50"
    }
  }
}

GET /api/opportunities/[id]

Retrieve detailed information about a specific opportunity.

Method: GET
Authentication: Optional (affects content visibility)
Rate Limit: 200 requests per minute

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Unique opportunity identifier

Example Request

GET /api/opportunities/opp_123456

Response Schema

{
  "success": true,
  "data": {
    "opportunity": {
      "id": "opp_123456",
      "title": "Senior Full-Stack Developer",
      "description": "Detailed job description with full requirements and expectations...",
      "short_description": "Senior developer position with modern tech stack",
      "category": "Software Development",
      "type": "job",
      "budget": {
        "min": 3000,
        "max": 5000,
        "currency": "USD",
        "per": "month"
      },
      "location": {
        "city": "Kyiv",
        "country": "Ukraine",
        "remote": true,
        "timezone": "Europe/Kiev",
        "address": "Optional office address"
      },
      "requirements": [
        "5+ years of full-stack development experience",
        "Expert knowledge of React and Node.js",
        "TypeScript proficiency",
        "English B2+ level"
      ],
      "benefits": [
        "Flexible working hours",
        "Health and dental insurance",
        "Professional development budget",
        "Modern office in city center"
      ],
      "entity": {
        "id": "entity_456",
        "name": "TechCorp Ukraine",
        "logo": "https://storage.com/logos/techcorp.png",
        "website": "https://techcorp.ua",
        "employee_count": "50-100"
      },
      "contact_person": {
        "name": "Anna Kovalenko",
        "position": "HR Manager",
        "email": "anna@techcorp.ua",
        "phone": "+380123456789"
      },
      "application_process": {
        "method": "form",
        "instructions": "Please fill out the application form and attach your CV",
        "required_documents": ["CV", "Cover Letter", "Portfolio"]
      },
      "attachments": [
        {
          "id": "att_789",
          "name": "detailed_job_description.pdf",
          "url": "https://storage.com/attachments/detailed_job.pdf",
          "size": 512000,
          "uploaded_at": "2024-01-15T10:00:00Z"
        }
      ],
      "tags": ["react", "nodejs", "typescript", "remote", "fintech"],
      "status": "active",
      "visibility": "public",
      "created_at": "2024-01-15T10:00:00Z",
      "updated_at": "2024-01-16T14:30:00Z",
      "expires_at": "2024-03-15T23:59:59Z",
      "views": 245,
      "applications": 12,
      "is_featured": false
    }
  }
}

POST /api/opportunities/create

Create a new opportunity posting.

Method: POST
Authentication: Required (Member role or higher)
Rate Limit: 10 requests per minute

Request Body Schema

{
  "title": "Senior Full-Stack Developer",
  "description": "We are looking for an experienced full-stack developer to join our growing team...",
  "short_description": "Senior developer position with modern tech stack",
  "category": "Software Development",
  "type": "job",
  "budget": {
    "min": 3000,
    "max": 5000,
    "currency": "USD",
    "per": "month"
  },
  "location": {
    "city": "Kyiv",
    "country": "Ukraine",
    "remote": true
  },
  "requirements": [
    "5+ years of experience",
    "React, Node.js proficiency",
    "English B2+"
  ],
  "benefits": [
    "Flexible schedule",
    "Health insurance"
  ],
  "entity_id": "entity_456",
  "contact_person": {
    "name": "Anna Kovalenko",
    "position": "HR Manager",
    "email": "anna@techcorp.ua"
  },
  "application_process": {
    "method": "email",
    "contact": "hr@techcorp.ua",
    "instructions": "Send CV and cover letter"
  },
  "tags": ["react", "nodejs", "typescript"],
  "expires_at": "2024-03-15T23:59:59Z",
  "visibility": "public"
}

Response Schema

{
  "success": true,
  "data": {
    "opportunity": {
      "id": "opp_new123456",
      "title": "Senior Full-Stack Developer",
      "status": "pending",
      "created_at": "2024-01-20T15:30:00Z"
    }
  },
  "message": "Opportunity created successfully and is pending review"
}

PUT /api/opportunities/update

Update an existing opportunity.

Method: PUT
Authentication: Required (Owner or Admin)
Rate Limit: 20 requests per minute

Request Body Schema

{
  "id": "opp_123456",
  "title": "Updated Senior Full-Stack Developer Position",
  "description": "Updated description with new requirements...",
  "budget": {
    "min": 3500,
    "max": 5500,
    "currency": "USD",
    "per": "month"
  },
  "status": "active",
  "updated_fields": ["title", "description", "budget"]
}

Response Schema

{
  "success": true,
  "data": {
    "opportunity": {
      "id": "opp_123456",
      "updated_at": "2024-01-20T16:45:00Z"
    }
  },
  "message": "Opportunity updated successfully"
}

DELETE /api/opportunities/delete/[id]

Delete an opportunity posting.

Method: DELETE
Authentication: Required (Owner or Admin)
Rate Limit: 10 requests per minute

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	Unique opportunity identifier

Response Schema

{
  "success": true,
  "message": "Opportunity deleted successfully"
}

POST /api/opportunities/upload

Upload files and attachments for opportunities.

Method: POST
Authentication: Required
Content-Type: multipart/form-data
Rate Limit: 5 requests per minute
File Size Limit: 10MB per file

Form Data Parameters

Parameter	Type	Required	Description
`file`	File	Yes	File to upload
`opportunity_id`	string	Yes	Opportunity identifier
`description`	string	No	File description

Response Schema

{
  "success": true,
  "data": {
    "attachment": {
      "id": "att_789012",
      "name": "job_requirements.pdf",
      "url": "https://storage.com/attachments/job_req.pdf",
      "size": 245760,
      "uploaded_at": "2024-01-20T17:00:00Z"
    }
  }
}

GET /api/confidential/opportunities

Access confidential opportunities for premium members.

Method: GET
Authentication: Required (Confidential role or higher)
Rate Limit: 50 requests per minute

Query Parameters

Same parameters as the regular opportunities endpoint.

Response Schema

Similar structure to regular opportunities but includes confidential content and additional premium features.

Search and Filtering

Advanced Search

The opportunities API supports sophisticated search capabilities:

Full-text search across titles and descriptions
Multi-field filtering with AND/OR logic
Range queries for budget and dates
Geolocation search with radius support
Tag-based filtering with multiple tags

Example Advanced Search

GET /api/opportunities?search=React%20developer&category=Software%20Development&budget_min=2000&remote=true&tags=react,typescript&sort=created_at&order=desc

Webhooks

The Opportunities API supports webhooks for real-time notifications:

Available Events

opportunity.created - New opportunity posted
opportunity.updated - Opportunity modified
opportunity.deleted - Opportunity removed
opportunity.expired - Opportunity expired
application.submitted - New application received

Webhook Configuration

{
  "url": "https://your-app.com/webhooks/opportunities",
  "events": ["opportunity.created", "application.submitted"],
  "secret": "webhook_secret_key"
}

Rate Limiting

Rate limits are enforced per authenticated user or IP address:

Endpoint	Rate Limit
GET endpoints	100-200 req/min
POST/PUT endpoints	10-20 req/min
File uploads	5 req/min
Confidential access	50 req/min

Rate limit headers are included in all responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642780800

Error Handling

The API uses standard HTTP status codes and provides detailed error information:

Common Error Codes

400 Bad Request - Invalid request parameters
401 Unauthorized - Authentication required
403 Forbidden - Insufficient permissions
404 Not Found - Opportunity not found
409 Conflict - Duplicate opportunity
422 Unprocessable Entity - Validation errors
429 Too Many Requests - Rate limit exceeded
500 Internal Server Error - Server error

Error Response Format

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": {
      "field": "budget.min",
      "reason": "Must be a positive number"
    },
    "timestamp": "2024-01-20T18:00:00Z"
  }
}

SDK and Integration

JavaScript/TypeScript SDK

import { OpportunitiesAPI } from '@ring/api-client'

const api = new OpportunitiesAPI({
  apiKey: 'your_api_key',
  baseURL: 'https://ring.platform/api'
})

// List opportunities
const opportunities = await api.list({
  category: 'Software Development',
  remote: true,
  limit: 20
})

// Create opportunity
const newOpportunity = await api.create({
  title: 'Senior Developer',
  category: 'Software Development',
  type: 'job',
  entity_id: 'entity_123'
})

cURL Examples

# List opportunities
curl -X GET "https://ring.platform/api/opportunities?category=Software%20Development" \
  -H "Authorization: Bearer your_token"

# Create opportunity
curl -X POST "https://ring.platform/api/opportunities/create" \
  -H "Authorization: Bearer your_token" \
  -H "Content-Type: application/json" \
  -d '{"title": "Senior Developer", "category": "Software Development"}'

Data Models

Opportunity Schema

interface Opportunity {
  id: string
  title: string
  description: string
  short_description?: string
  category: string
  type: 'job' | 'project' | 'collaboration'
  budget?: {
    min?: number
    max?: number
    currency: string
    per: 'hour' | 'day' | 'month' | 'project'
  }
  location: {
    city?: string
    country?: string
    remote: boolean
    timezone?: string
  }
  requirements: string[]
  benefits: string[]
  entity_id: string
  entity?: Entity
  contact_person?: ContactPerson
  application_process: ApplicationProcess
  attachments: Attachment[]
  tags: string[]
  status: 'draft' | 'pending' | 'active' | 'expired' | 'closed'
  visibility: 'public' | 'members' | 'confidential'
  created_at: string
  updated_at: string
  expires_at?: string
  views: number
  applications: number
  is_featured: boolean
}

The Opportunities API provides a comprehensive, scalable solution for managing job postings and project opportunities with full internationalization support and optimized performance.

Base URL​

Authentication​

Endpoints Overview​

Core Endpoints​

GET /api/opportunities​

Query Parameters​

Example Request​

Response Schema​

Error Responses​

GET /api/opportunities/[id]​

Path Parameters​

Example Request​

Response Schema​

POST /api/opportunities/create​

Request Body Schema​

Response Schema​

PUT /api/opportunities/update​

Request Body Schema​

Response Schema​

DELETE /api/opportunities/delete/[id]​

Path Parameters​

Response Schema​

POST /api/opportunities/upload​

Form Data Parameters​

Response Schema​

GET /api/confidential/opportunities​

Query Parameters​

Response Schema​

Search and Filtering​

Advanced Search​

Example Advanced Search​

Webhooks​

Available Events​

Webhook Configuration​

Rate Limiting​

Error Handling​

Common Error Codes​

Error Response Format​

SDK and Integration​

JavaScript/TypeScript SDK​

cURL Examples​

Data Models​

Opportunity Schema​

Base URL

Authentication

Endpoints Overview

Core Endpoints

GET /api/opportunities

Query Parameters

Example Request

Response Schema

Error Responses

GET /api/opportunities/[id]

Path Parameters

Example Request

Response Schema

POST /api/opportunities/create

Request Body Schema

Response Schema

PUT /api/opportunities/update

Request Body Schema

Response Schema

DELETE /api/opportunities/delete/[id]

Path Parameters

Response Schema

POST /api/opportunities/upload

Form Data Parameters

Response Schema

GET /api/confidential/opportunities

Query Parameters

Response Schema

Search and Filtering

Advanced Search

Example Advanced Search

Webhooks

Available Events

Webhook Configuration

Rate Limiting

Error Handling

Common Error Codes

Error Response Format

SDK and Integration

JavaScript/TypeScript SDK

cURL Examples

Data Models

Opportunity Schema