Projects

A project represents a hackathon project submission — the thing a team builds and submits at an event. A project records the basics (name, description, source and demo links, what it was built with) and links to the people and submissions around it: the users on the team (project_users), the submissions it was entered into (project_submissions), and any challenge submission it maps to (challenge_submission).

These endpoints follow the standard REST shape. See Making requests for pagination, filtering, expanding, and error responses, and Authentication for how to authenticate.

Endpoints

Method	Path	What it does
GET	/v4/projects	List projects (paginated, filterable)
GET	/v4/projects/{id}	Get one project
POST	/v4/projects	Create a project
PATCH / PUT	/v4/projects/{id}	Update a project
DELETE	/v4/projects/{id}	Delete a project
GET	/v4/projects/identify	Find a project by identifier (optionally create it)

Fields

Set these when you create or update a project, and read them back on responses.

Field	Required	What it is	Example
name	Required	The project's title.	"Sign Language Translator"
description	Required	What the project does.	"Translates ASL to text in real time."
source_url	Required	Link to the source code.	"https://github.com/team/asl"
demo_live_url	Optional	Link to a live demo.	"https://asl.example.com"
demo_video_url	Optional	Link to a demo video.	"https://youtu.be/abc123"
built_with	Optional	Technologies used, as a list of strings.	["python", "react", "opencv"]
team_member_count	Optional	Number of people on the team.	4
custom_fields	Optional	Free-form object for extra data.	{ "track": "AI" }
project_submissions	Optional	IDs of the submissions this project belongs to.	["a1b2..."]
project_users	Optional	IDs of the users on the team.	["c3d4..."]
challenge_submission	Optional	ID of the linked challenge submission.	"e5f6..."
screenshots	Optional	IDs of attached screenshots.	["g7h8..."]

Read-only fields (set by the server, returned on responses — don't send them):

• id — the project's unique identifier (UUID).
• created_at — when the project was created, as a Unix timestamp (seconds).
• updated_at — when the project was last updated, as a Unix timestamp.

By default a response returns the project's own fields. Use expand[] to include related records: project_submissions, project_users, challenge_submission, screenshots. See Making requests.

GET /v4/projects/{id}?expand[]=project_users&expand[]=screenshots

Scopes

These endpoints use the project scope (project data access). Request only the scopes your integration needs — see Authentication.

Notable endpoints

Identify a project

GET /v4/projects/identify

Looks up a project by an identifier — an email address or phone number of a user associated with the project — and returns the matching project.

Parameter	Required	What it does
identifier	Required	Email address or phone number to identify the project by.
auto_create	Optional	If true, creates the project when no match is found. Defaults to false.

GET /v4/projects/identify?identifier=team@example.com&auto_create=true

When auto_create is false (the default) and nothing matches, the endpoint returns 404.

Delete a project

DELETE /v4/projects/{id}

Deletes the project with the given id. This is permanent.

Examples

Create a project:

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

{
  "name": "Sign Language Translator",
  "description": "Translates ASL to text in real time.",
  "source_url": "https://github.com/team/asl",
  "built_with": ["python", "react", "opencv"],
  "team_member_count": 4
}

Update a project:

PATCH /v4/projects/{id}
Content-Type: application/json

{
  "demo_video_url": "https://youtu.be/abc123"
}

List and filter projects:

GET /v4/projects?name[contains]=translator&limit=50

Managing projects per user

Projects can also be managed against a specific user at /v4/users/{user_id}/projects, which performs an upsert (POST/PUT) and lists that user's projects (GET). Use this when you're working from a known user rather than the project's own ID. See Users.

Related

• V4 API overview
• Making requests — pagination, filtering, expanding, errors.
• Authentication — auth methods and scopes.
• Users — the people on a project's team.
• Challenges — challenges and challenge submissions.