Projects

Project endpoints allow you to create, read, update, and delete projects. Projects are containers for pages, QR codes, templates, and files.

Project Status Values

Value	Status
1	ACTIVE
2	INACTIVE
3	SUSPENDED

List Projects

Get a list of all projects accessible to the authenticated user.

GET https://v1.freeqr.io/api/projects

Requires Authentication: Yes

Query Parameters

Parameter	Type	Required	Description
page	integer	No	Page number (default: 1)
limit	integer	No	Items per page (default: 10, max: 100)
sort	string	No	Sort field (prefix with - for descending)

Response

{
  "data": [
    {
      "id": "01arz3ndektsv4rrffq69g5fav",
      "status": 1,
      "name": "My Project",
      "pages_count": 5,
      "files_count": 10,
      "size": 1024000,
      "created_at": "2024-01-01T00:00:00.000000Z",
      "project_user": {
        "is_billing": true,
        "is_super": true,
        "abilities": ["view", "update"]
      }
    }
  ],
  "meta": {
    "total": 1
  }
}

Create Project

Create a new project.

POST https://v1.freeqr.io/api/projects

Requires Authentication: Yes

Request Body

{
  "name": "My New Project"
}

Parameters

Parameter	Type	Required	Description
name	string	Yes	Project name (min 1, max 60 characters)

Response

{
  "id": "01arz3ndektsv4rrffq69g5fav",
  "status": 1,
  "name": "My New Project",
  "pages_count": 0,
  "files_count": 0,
  "size": 0,
  "created_at": "2024-01-01T00:00:00.000000Z",
  "project_user": {
    "is_billing": true,
    "is_super": true,
    "abilities": []
  }
}

Note: The creator is automatically added as a super user and billing user.

Get Project

Get a specific project by ID.

GET https://v1.freeqr.io/api/projects/{id}

Requires Authentication: Yes

Path Parameters

Parameter	Type	Required	Description
id	string (ULID)	Yes	Project ID

Response

{
  "id": "01arz3ndektsv4rrffq69g5fav",
  "status": 1,
  "name": "My Project",
  "pages_count": 5,
  "files_count": 10,
  "size": 1024000,
  "created_at": "2024-01-01T00:00:00.000000Z",
  "project_user": {
    "is_billing": true,
    "is_super": true,
    "abilities": ["view", "update"]
  }
}

Update Project

Update an existing project.

PATCH https://v1.freeqr.io/api/projects/{id}

Requires Authentication: Yes

Path Parameters

Parameter	Type	Required	Description
id	string (ULID)	Yes	Project ID

Request Body

{
  "name": "Updated Project Name"
}

Parameters

Parameter	Type	Required	Description
name	string	No	Project name (min 1, max 60 characters)

Response

{
  "id": "01arz3ndektsv4rrffq69g5fav",
  "status": 1,
  "name": "Updated Project Name",
  "pages_count": 5,
  "files_count": 10,
  "size": 1024000,
  "created_at": "2024-01-01T00:00:00.000000Z",
  "project_user": {
    "is_billing": true,
    "is_super": true,
    "abilities": ["view", "update"]
  }
}

Delete Project

Delete a project.

DELETE https://v1.freeqr.io/api/projects/{id}

Requires Authentication: Yes

Path Parameters

Parameter	Type	Required	Description
id	string (ULID)	Yes	Project ID

Response

Returns the deleted project resource (same structure as Get Project).

Get Project Users

Get all users associated with a project. Returns a list of users ordered by ID.

GET https://v1.freeqr.io/api/projects/{project}/users

Requires Authentication: Yes

Path Parameters

Parameter	Type	Required	Description
project	string (ULID)	Yes	Project ID

Query Parameters

This endpoint does not support query parameters. Results are returned ordered by user ID.

Response

{
  "data": [
    {
      "id": "01arz3ndektsv4rrffq69g5fav",
      "email": "[email protected]",
      "name": "John Doe",
      "passwordless_login": false,
      "password_set": true,
      "project_user": {
        "is_billing": false,
        "is_super": true,
        "abilities": ["view", "update"]
      }
    }
  ]
}

Note: This endpoint returns all users without pagination. Results are ordered by user ID in ascending order.

Attach User to Project

Add a user to a project.

POST https://v1.freeqr.io/api/projects/{project}:attach_user

Requires Authentication: Yes

Path Parameters

Parameter	Type	Required	Description
project	string (ULID)	Yes	Project ID

Request Body

{
  "email": "[email protected]",
  "is_super": false,
  "is_billing": false,
  "abilities": ["view", "update"]
}

Parameters

Parameter	Type	Required	Description
email	string	Yes	User email (ASCII only, max 255 characters). User will be created if doesn't exist.
is_super	boolean	No	Whether user is a super user
is_billing	boolean	No	Whether user is the billing user (requires update ability if not super)
abilities	array	No	Array of abilities: ["view"], ["update"], or ["view", "update"]

Constraints

• Maximum 100 users per project
• Maximum 100 projects per user
• Cannot unset the last superuser
• Billing user must have update ability (unless super)

Response

{
  "id": "01arz3ndektsv4rrffq69g5fav",
  "user_id": "01arz3ndektsv4rrffq69g5fav",
  "project_id": "01arz3ndektsv4rrffq69g5fav",
  "is_billing": false,
  "is_super": false,
  "abilities": ["view", "update"],
  "created_at": "2024-01-01T00:00:00.000000Z",
  "updated_at": "2024-01-01T00:00:00.000000Z"
}

Note: An email notification is sent to the user when they are attached.

Detach User from Project

Remove a user from a project.

POST https://v1.freeqr.io/api/projects/{project}:detach_user

Requires Authentication: Yes

Path Parameters

Parameter	Type	Required	Description
project	string (ULID)	Yes	Project ID

Request Body

{
  "email": "[email protected]"
}

Parameters

Parameter	Type	Required	Description
email	string	Yes	User email (must exist, ASCII only, max 255 characters)

Constraints

• Cannot detach billing user
• Cannot detach the last superuser

Response

{
  "meta": {
    "status": "success"
  }
}

Note: An email notification is sent to the user when they are detached.