Opportunities API - FTB Hustle

The Opportunities API allows you to create, retrieve, update, and delete opportunity listings on FTB Hustle.

Authentication

All Opportunities API endpoints require authentication. Users must be logged in to access these endpoints.

User Roles

user: Regular users can create opportunities that require admin approval before being published
member: Members can create opportunities that are published immediately
admin: Admins can create, edit, and delete any opportunity, and view all opportunities including pending ones

List Opportunities

curl -X GET "https://ftbhustle.com/api/opportunities?limit=10&offset=0" \
  -H "Cookie: session=YOUR_SESSION_TOKEN"

Retrieve a paginated list of opportunities with optional filtering and search.

Query Parameters

limit

number

default:"10"

Number of opportunities to return (1-50)

offset

number

default:"0"

Number of opportunities to skip for pagination

string

Search term to filter opportunities by title or description

types

string

Comma-separated list of opportunity types to filter by (hackathon, grant, competition, ideathon)

tags

string

Comma-separated list of tags to filter by (case-insensitive)

ids

string

Comma-separated list of opportunity IDs to retrieve specific opportunities

includeTotal

boolean

default:"false"

Whether to include an accurate total count in the response

Response

success

boolean

Indicates if the request was successful

opportunities

array

Array of opportunity objects

Show Opportunity Object

string

Unique identifier for the opportunity

type

string

Type of opportunity: hackathon, grant, competition, or ideathon

title

string

Opportunity title

description

string

Detailed description of the opportunity

images

array

Array of image URLs

tags

array

Array of tag strings

location

string

Location of the opportunity

organiserInfo

string

Information about the organizer

startDate

string

Start date in YYYY-MM-DD format

endDate

string

End date in YYYY-MM-DD format

publishAt

string

Scheduled publish date/time (ISO 8601 format)

isVerified

boolean

Whether the opportunity has been verified

isActive

boolean

Whether the opportunity is active and visible to non-admin users

isFlagged

boolean

Whether the opportunity has been flagged for review

upvoteCount

number

Number of upvotes

userHasUpvoted

boolean

Whether the current user has upvoted this opportunity

userId

string

ID of the user who created the opportunity

user

object

User information

Show User Object

string

User ID

name

string

User name

image

string

User profile image URL

role

string

User role (user, member, admin)

createdAt

string

Creation timestamp (ISO 8601 format)

updatedAt

string

Last update timestamp (ISO 8601 format)

pagination

object

Pagination metadata

Show Pagination Object

{
  "success": true,
  "opportunities": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "type": "hackathon",
      "title": "Tech Innovation Hackathon 2024",
      "description": "Join us for a 48-hour hackathon focused on AI and sustainability",
      "images": ["https://example.com/image1.jpg"],
      "tags": ["AI", "Sustainability", "Innovation"],
      "location": "San Francisco, CA",
      "organiserInfo": "TechCorp",
      "startDate": "2024-06-15",
      "endDate": "2024-06-17",
      "publishAt": null,
      "isVerified": true,
      "isActive": true,
      "isFlagged": false,
      "upvoteCount": 42,
      "userHasUpvoted": false,
      "userId": "user123",
      "user": {
        "id": "user123",
        "name": "John Doe",
        "image": "https://example.com/avatar.jpg",
        "role": "member"
      },
      "createdAt": "2024-03-01T10:00:00Z",
      "updatedAt": "2024-03-01T10:00:00Z"
    }
  ],
  "pagination": {
    "limit": 10,
    "offset": 0,
    "total": 156,
    "hasMore": true
  }
}

Create Opportunity

curl -X POST "https://ftbhustle.com/api/opportunities" \
  -H "Cookie: session=YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "hackathon",
    "title": "AI Hackathon 2024",
    "description": "Build innovative AI solutions",
    "tags": ["AI", "Machine Learning"],
    "location": "New York, NY",
    "startDate": "2024-07-01",
    "endDate": "2024-07-03"
  }'

Create a new opportunity listing.

Request Body

type

string

required

Type of opportunity. Must be one of: hackathon, grant, competition, ideathon

title

string

required

Opportunity title (minimum 1 character)

description

string

required

Detailed description (minimum 1 character)

images

array

Array of image URL strings

tags

array

Array of tag strings for categorization

location

string

Location of the opportunity

organiserInfo

string

Information about the organizer

startDate

string

Start date (ISO 8601 format or YYYY-MM-DD)

endDate

string

End date (ISO 8601 format or YYYY-MM-DD)

publishAt

string

Scheduled publish date/time (ISO 8601 format). Pass empty string or null to publish immediately

Response

success

boolean

Indicates if the opportunity was created successfully

data

object

The created opportunity object

userRole

string

The role of the user who created the opportunity

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "hackathon",
    "title": "AI Hackathon 2024",
    "description": "Build innovative AI solutions",
    "images": [],
    "tagIds": ["tag-id-1", "tag-id-2"],
    "location": "New York, NY",
    "organiserInfo": null,
    "startDate": "2024-07-01",
    "endDate": "2024-07-03",
    "publishAt": null,
    "isFlagged": false,
    "isVerified": false,
    "isActive": false,
    "upvoteCount": 0,
    "upvoterIds": [],
    "userId": "user123",
    "createdAt": "2024-03-15T14:30:00Z",
    "updatedAt": "2024-03-15T14:30:00Z",
    "deletedAt": null
  },
  "userRole": "user"
}

Update Opportunity

curl -X PUT "https://ftbhustle.com/api/opportunities/550e8400-e29b-41d4-a716-446655440000" \
  -H "Cookie: session=YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Updated AI Hackathon 2024",
    "location": "San Francisco, CA"
  }'

Update an existing opportunity. Only the opportunity owner can update their own opportunities.

Path Parameters

string

required

The unique identifier of the opportunity to update

Request Body

All fields are optional. Only provided fields will be updated.

type

string

Type of opportunity: hackathon, grant, competition, or ideathon

title

string

Opportunity title

description

string

Detailed description

images

array

Array of image URLs

tags

array

Array of tag strings

location

string

Location

organiserInfo

string

Organizer information

startDate

string

Start date

endDate

string

End date

publishAt

string

Scheduled publish date/time

Response

success

boolean

Indicates if the update was successful

data

object

The updated opportunity object

Error Responses

error

string

Error message

401 Unauthorized: User is not authenticated
403 Forbidden: User doesn’t have permission to edit this opportunity
404 Not Found: Opportunity not found
400 Bad Request: Validation error

Delete Opportunity

curl -X DELETE "https://ftbhustle.com/api/opportunities/550e8400-e29b-41d4-a716-446655440000" \
  -H "Cookie: session=YOUR_SESSION_TOKEN"

Soft delete an opportunity. Only the opportunity owner can delete their own opportunities.

Path Parameters

string

required

The unique identifier of the opportunity to delete

Response

message

string

Success message

{
  "message": "Opportunity deleted successfully"
}

Error Responses

401 Unauthorized: User is not authenticated
403 Forbidden: User doesn’t have permission to delete this opportunity
404 Not Found: Opportunity not found

Error Handling

All API endpoints return appropriate HTTP status codes and error messages:

Error Response Example

{
  "error": "Validation error message"
}

For validation errors from Zod:

Validation Error Response

{
  "error": [
    {
      "code": "too_small",
      "minimum": 1,
      "path": ["title"],
      "message": "Title is required"
    }
  ]
}

Upvote Opportunity

Get Upvote Status

curl -X GET "https://ftbhustle.com/api/opportunities/550e8400-e29b-41d4-a716-446655440000/upvote" \
  -H "Cookie: session=YOUR_SESSION_TOKEN"

Get the upvote count and whether the current user has upvoted this opportunity.

Response

count

number

Total number of upvotes

userHasUpvoted

boolean

Whether the current user has upvoted this opportunity

{
  "count": 42,
  "userHasUpvoted": true
}

Toggle Upvote

curl -X POST "https://ftbhustle.com/api/opportunities/550e8400-e29b-41d4-a716-446655440000/upvote" \
  -H "Cookie: session=YOUR_SESSION_TOKEN"

Toggle the current user’s upvote on an opportunity. If the user has already upvoted, this removes the upvote. If not, it adds an upvote.

Response

success

boolean

Indicates if the toggle was successful

userHasUpvoted

boolean

New upvote status for the current user

count

number

Updated total upvote count

{
  "success": true,
  "userHasUpvoted": true,
  "count": 43
}

Comments

Get Comments

curl -X GET "https://ftbhustle.com/api/opportunities/550e8400-e29b-41d4-a716-446655440000/comments" \
  -H "Cookie: session=YOUR_SESSION_TOKEN"

Retrieve all comments for an opportunity, ordered by newest first.

Response

comments

array

Array of comment objects with user information

Show Comment Object

string

Unique comment identifier

content

string

Comment content (sanitized)

createdAt

string

Creation timestamp

updatedAt

string

Last update timestamp

userId

string

ID of the user who posted the comment

opportunityId

string

ID of the opportunity

user

object

User information

Show User Object

string

User ID

name

string

User’s name

image

string

User’s avatar URL

Post Comment

curl -X POST "https://ftbhustle.com/api/opportunities/550e8400-e29b-41d4-a716-446655440000/comments" \
  -H "Cookie: session=YOUR_SESSION_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Great opportunity!"
  }'

Post a new comment on an opportunity. Comments are automatically sanitized to remove HTML/script tags.

Request Body

content

string

required

Comment content (1-1000 characters). HTML tags and scripts will be stripped.

Response

comment

object

The created comment with user information

message

string

Success message

{
  "comment": {
    "id": "comment-uuid",
    "content": "Great opportunity!",
    "createdAt": "2024-03-15T14:30:00Z",
    "updatedAt": "2024-03-15T14:30:00Z",
    "userId": "user123",
    "opportunityId": "550e8400-e29b-41d4-a716-446655440000",
    "user": {
      "id": "user123",
      "name": "John Doe",
      "image": "https://example.com/avatar.jpg"
    }
  },
  "message": "Comment posted successfully"
}

Delete Comment

curl -X DELETE "https://ftbhustle.com/api/opportunities/550e8400-e29b-41d4-a716-446655440000/comments/comment-uuid" \
  -H "Cookie: session=YOUR_SESSION_TOKEN"

Delete a comment. Only the comment author can delete their own comments.

Path Parameters

string

required

Opportunity ID

commentId

string

required

Comment ID to delete

Response

message

string

Success message

{
  "message": "Comment deleted successfully"
}

Error Responses

401 Unauthorized: User is not authenticated
404 Not Found: Comment not found or user doesn’t have permission to delete it

Documentation Index

​Authentication

​User Roles

​List Opportunities

​Query Parameters

​Response

​Create Opportunity

​Request Body

​Response

​Update Opportunity

​Path Parameters

​Request Body

​Response

​Error Responses

​Delete Opportunity

​Path Parameters

​Response

​Error Responses

​Error Handling

​Upvote Opportunity

​Get Upvote Status

​Response

​Toggle Upvote

​Response

​Comments

​Get Comments

​Response

​Post Comment

​Request Body

​Response

​Delete Comment

​Path Parameters

​Response

​Error Responses

Authentication

User Roles

List Opportunities

Query Parameters

Response

Create Opportunity

Request Body

Response

Update Opportunity

Path Parameters

Request Body

Response

Error Responses

Delete Opportunity

Path Parameters

Response

Error Responses

Error Handling

Upvote Opportunity

Get Upvote Status

Response

Toggle Upvote

Response

Comments

Get Comments

Response

Post Comment

Request Body

Response

Delete Comment

Path Parameters

Response

Error Responses