{ "openapi": "3.1.0", "info": { "title": "Hub01 Shop", "version": "0.0.1", "description": "## Introduction\n\nThe **Hub01 Shop API** enables users to interact programmatically with the platform, allowing you to explore projects and manage your own resources.\n\nYou can query all available resources in the application, but currently, management capabilities are limited to project versions. Future updates will expand support for managing additional resources.\n\n---\n\n## Authentication\n\nAccess to certain API endpoints requires authentication using **API tokens**. These tokens can be generated directly from your user profile.\n\n---\n\n### Generating API Tokens\n\n1. **Navigate** to your user profile.\n2. **Select** the **API Tokens** section.\n3. **Click** on **Create API Token**.\n4. **Provide** a custom name and, optionally, set an expiration date.\n5. **Include** the generated token in the `Authorization` header of your API requests as a **Bearer token**." }, "servers": [ { "url": "https://hub01-shop.srgnis.com/api" } ], "tags": [ { "name": "Project Types" }, { "name": "Projects" } ], "paths": { "/v1/project_types": { "get": { "operationId": "v1.project_types", "description": "Returns all the project types defined in the application", "summary": "List project types", "tags": ["Project Types"], "responses": { "200": { "description": "Array of `ProjectTypeResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectTypeResource" } } }, "required": ["data"] } } } } } } }, "/v1/project_type/{slug}": { "get": { "operationId": "v1.project_type", "description": "Returns the project type with the given slug", "summary": "Get a project type", "tags": ["Project Types"], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`ProjectTypeResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProjectTypeResource" } }, "required": ["data"] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" } } } }, "/v1/projects": { "get": { "operationId": "v1.projects", "description": "Returns a filtered list of projects", "summary": "Search projects", "tags": ["Projects"], "parameters": [ { "name": "project_type", "in": "query", "schema": { "type": ["string", "null"] } }, { "name": "search", "in": "query", "schema": { "type": ["string", "null"], "maxLength": 255 } }, { "name": "order_by", "in": "query", "schema": { "type": ["string", "null"], "enum": [ "name", "created_at", "updated_at", "downloads", "favorites" ] } }, { "name": "order_direction", "in": "query", "schema": { "type": ["string", "null"], "enum": ["asc", "desc"] } }, { "name": "per_page", "in": "query", "schema": { "type": ["integer", "null"], "enum": ["10", "25", "50", "100"] } }, { "name": "release_date_period", "in": "query", "schema": { "type": ["string", "null"], "enum": [ "all", "last_30_days", "last_90_days", "last_year", "custom" ] } }, { "name": "release_date_start", "in": "query", "schema": { "type": ["string", "null"], "format": "date-time" } }, { "name": "release_date_end", "in": "query", "schema": { "type": ["string", "null"], "format": "date-time" } }, { "name": "tags[]", "in": "query", "description": "The tags slugs to filter by", "schema": { "type": "array", "items": {} }, "example": "tags[]=tag1&tags[]=tag2" }, { "name": "version_tags[]", "in": "query", "description": "The version tags slugs to filter by", "schema": { "type": "array", "items": {} }, "example": "version_tags[]=tag1&version_tags[]=tag2" } ], "responses": { "200": { "description": "Return paginated JSON response\n\n\n\nPaginated set of `ProjectResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectResource" } }, "links": { "type": "object", "properties": { "first": { "type": ["string", "null"] }, "last": { "type": ["string", "null"] }, "prev": { "type": ["string", "null"] }, "next": { "type": ["string", "null"] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": ["integer", "null"], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": ["string", "null"], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": ["integer", "null"], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": ["data", "links", "meta"] } } } }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/v1/project/{slug}": { "get": { "operationId": "v1.project", "description": "Returns the project with the given slug", "summary": "Get a project", "tags": ["Projects"], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`ProjectResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProjectResource" } }, "required": ["data"] } } } }, "404": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Project not found" } }, "required": ["message"] } } } } } } }, "/v1/collections": { "get": { "operationId": "v1.collections", "tags": ["Collection"], "parameters": [ { "name": "search", "in": "query", "schema": { "type": ["string", "null"], "maxLength": 255 } }, { "name": "order_by", "in": "query", "schema": { "type": ["string", "null"], "enum": ["name", "created_at", "updated_at"] } }, { "name": "order_direction", "in": "query", "schema": { "type": ["string", "null"], "enum": ["asc", "desc"] } }, { "name": "per_page", "in": "query", "schema": { "type": ["integer", "null"], "enum": ["10", "25", "50", "100"] } } ], "responses": { "200": { "description": "Paginated set of `CollectionResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CollectionResource" } }, "links": { "type": "object", "properties": { "first": { "type": ["string", "null"] }, "last": { "type": ["string", "null"] }, "prev": { "type": ["string", "null"] }, "next": { "type": ["string", "null"] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": ["integer", "null"], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": ["string", "null"], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": ["integer", "null"], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": ["data", "links", "meta"] } } } }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/v1/collection/hidden/{token}": { "get": { "operationId": "v1.collection.hidden", "tags": ["Collection"], "parameters": [ { "name": "token", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "token", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 255 } } ], "responses": { "200": { "description": "`CollectionResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CollectionResource" } }, "required": ["data"] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/v1/collection/{uid}": { "get": { "operationId": "v1.collection", "tags": ["Collection"], "parameters": [ { "name": "uid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`CollectionResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CollectionResource" } }, "required": ["data"] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "403": { "$ref": "#/components/responses/AuthorizationException" } } } }, "/v1/me/collections": { "get": { "operationId": "v1.me.collections", "tags": ["Collection"], "parameters": [ { "name": "search", "in": "query", "schema": { "type": ["string", "null"], "maxLength": 255 } }, { "name": "visibility", "in": "query", "schema": { "type": ["string", "null"], "enum": ["public", "private", "hidden"] } }, { "name": "order_by", "in": "query", "schema": { "type": ["string", "null"], "enum": ["name", "created_at", "updated_at"] } }, { "name": "order_direction", "in": "query", "schema": { "type": ["string", "null"], "enum": ["asc", "desc"] } }, { "name": "per_page", "in": "query", "schema": { "type": ["integer", "null"], "enum": ["10", "25", "50", "100"] } } ], "responses": { "200": { "description": "Paginated set of `CollectionResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CollectionResource" } }, "links": { "type": "object", "properties": { "first": { "type": ["string", "null"] }, "last": { "type": ["string", "null"] }, "prev": { "type": ["string", "null"] }, "next": { "type": ["string", "null"] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": ["integer", "null"], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": ["string", "null"], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": ["integer", "null"], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": ["data", "links", "meta"] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" }, "403": { "$ref": "#/components/responses/AuthorizationException" } } }, "post": { "operationId": "v1.me.collections.store", "tags": ["Collection"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionStoreRequest" } } } }, "responses": { "201": { "description": "`CollectionResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CollectionResource" }, "message": { "type": "string", "const": "Collection created successfully" } }, "required": ["data", "message"] } } } }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/v1/me/collection/{uid}": { "get": { "operationId": "v1.me.collection", "tags": ["Collection"], "parameters": [ { "name": "uid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`CollectionResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CollectionResource" } }, "required": ["data"] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "patch": { "operationId": "v1.me.collection.update", "tags": ["Collection"], "parameters": [ { "name": "uid", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionUpdateRequest" } } } }, "responses": { "200": { "description": "`CollectionResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CollectionResource" }, "message": { "type": "string", "const": "Collection updated successfully" } }, "required": ["data", "message"] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" }, "422": { "$ref": "#/components/responses/ValidationException" } } }, "delete": { "operationId": "v1.me.collection.destroy", "tags": ["Collection"], "parameters": [ { "name": "uid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/me/collections/quick-create-with-project": { "post": { "operationId": "v1.me.collections.quick_create", "tags": ["Collection"], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionQuickCreateRequest" } } } }, "responses": { "201": { "description": "`CollectionResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CollectionResource" }, "message": { "type": "string", "const": "Collection created and project attached successfully" } }, "required": ["data", "message"] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/me/collection/{uid}/entries": { "post": { "operationId": "v1.me.collection.entries.store", "tags": ["Collection"], "parameters": [ { "name": "uid", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionEntryStoreRequest" } } } }, "responses": { "201": { "description": "`CollectionResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CollectionResource" }, "message": { "type": "string", "const": "Collection entry added successfully" } }, "required": ["data", "message"] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/me/collection/{uid}/entry/{entryUid}": { "delete": { "operationId": "v1.me.collection.entry.destroy", "tags": ["Collection"], "parameters": [ { "name": "uid", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "entryUid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "422": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string" } }, "required": ["message"] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/me/collection/{uid}/entry/{entryUid}/note": { "patch": { "operationId": "v1.me.collection.entry.note.update", "tags": ["Collection"], "parameters": [ { "name": "uid", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "entryUid", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionEntryUpdateNoteRequest" } } } }, "responses": { "200": { "description": "`CollectionResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CollectionResource" }, "message": { "type": "string", "const": "Collection entry note updated successfully" } }, "required": ["data", "message"] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/me/collection/{uid}/entries/reorder": { "post": { "operationId": "v1.me.collection.entries.reorder", "tags": ["Collection"], "parameters": [ { "name": "uid", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectionEntryReorderRequest" } } } }, "responses": { "200": { "description": "`CollectionResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/CollectionResource" }, "message": { "type": "string", "const": "Collection entries reordered successfully" } }, "required": ["data", "message"] } } } }, "422": { "$ref": "#/components/responses/ValidationException" }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "403": { "$ref": "#/components/responses/AuthorizationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/project/{slug}/versions": { "get": { "operationId": "v1.project_versions", "summary": "List all versions of a project", "tags": ["ProjectVersion"], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "The project slug", "schema": { "type": "string" } }, { "name": "tags[]", "in": "query", "description": "The version tags slugs to filter by", "schema": { "type": "array", "items": {} }, "example": "tags[]=tag1&tags[]=tag2" }, { "name": "order_by", "in": "query", "description": "The field to order by", "schema": { "type": ["string", "null"], "enum": ["version", "release_date", "downloads"], "default": "downloads" } }, { "name": "order_direction", "in": "query", "description": "The direction to order by", "schema": { "type": ["string", "null"], "enum": ["asc", "desc"], "default": "desc" } }, { "name": "per_page", "in": "query", "description": "The number of results per page", "schema": { "type": ["integer", "null"], "enum": ["10", "25", "50", "100"], "default": 10 } }, { "name": "release_date_period", "in": "query", "description": "The release date period to filter by", "schema": { "type": ["string", "null"], "enum": [ "all", "last_30_days", "last_90_days", "last_year", "custom" ], "default": "all" } }, { "name": "release_date_start", "in": "query", "description": "The start date to filter by, only used if release_date_period is custom", "schema": { "type": ["string", "null"], "format": "date-time" } }, { "name": "release_date_end", "in": "query", "description": "The end date to filter by, only used if release_date_period is custom", "schema": { "type": ["string", "null"], "format": "date-time" } } ], "responses": { "200": { "description": "Return paginated JSON response\n\n\n\nPaginated set of `ProjectVersionResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectVersionResource" } }, "links": { "type": "object", "properties": { "first": { "type": ["string", "null"] }, "last": { "type": ["string", "null"] }, "prev": { "type": ["string", "null"] }, "next": { "type": ["string", "null"] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": ["integer", "null"], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": ["string", "null"], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": ["integer", "null"], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": ["data", "links", "meta"] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "422": { "$ref": "#/components/responses/ValidationException" } } }, "post": { "operationId": "v1.project_version.store", "summary": "Create a new project version", "tags": ["ProjectVersion"], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "Bearer token", "schema": { "type": "string" }, "example": "Bearer {token}" }, { "name": "slug", "in": "path", "required": true, "description": "The project slug", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "dependencies": { "type": "string" }, "name": { "type": "string", "description": "The name of the version", "example": "Version 1.0.0" }, "version": { "type": "string", "description": "The version number (must be unique for the project)", "example": "1.0.0" }, "release_type": { "type": "string", "description": "The release type: `release`, `rc`, `beta`, or `alpha`", "example": "release" }, "release_date": { "type": "string", "format": "date", "description": "The release date", "example": "2024-01-15" }, "changelog": { "type": "string", "description": "The changelog for this version", "example": "Initial release" }, "tags[]": { "type": "array", "description": "Array of version tag slugs", "items": {} }, "files[]": { "type": "array", "description": "Array of files to upload", "items": { "type": "object", "description": "File to upload" } }, "dependencies[]": { "type": "array", "description": "Array of dependencies", "items": { "type": "object", "properties": { "project": { "type": "string", "description": "Project slug of the dependency" }, "version": { "type": "string", "description": "Version slug of the dependency" }, "type": { "type": "string", "description": "Dependency type: `required`, `optional` or `embedded`", "example": "required" }, "external": { "type": "boolean", "description": "If the dependency is linked to a project in the platform or is external", "default": true } }, "required": [ "project", "type", "external" ] } } }, "required": [ "name", "version", "release_type", "release_date", "files[]" ] } } } }, "responses": { "201": { "description": "`ProjectVersionResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProjectVersionResource" }, "message": { "type": "string", "const": "Version created successfully" } }, "required": ["data", "message"] } } } }, "403": { "description": "An error\n\nAn error", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "example": "This project has been deactivated and versions cannot be created." } }, "required": ["message"] }, { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "example": "You do not have permission to upload versions to this project." } }, "required": ["message"] } ] } } } }, "500": { "description": "An error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": ["message"] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/project/{slug}/version/{version}": { "get": { "operationId": "v1.project_version", "summary": "Get a project version", "tags": ["ProjectVersion"], "parameters": [ { "name": "slug", "in": "path", "required": true, "description": "The project slug", "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "description": "The project version", "schema": { "type": "string" } } ], "responses": { "200": { "description": "`ProjectVersionResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProjectVersionResource" } }, "required": ["data"] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" } } }, "post": { "operationId": "v1.project_version.update", "summary": "Update an existing project version", "tags": ["ProjectVersion"], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "Bearer token", "schema": { "type": "string" }, "example": "Bearer {token}" }, { "name": "slug", "in": "path", "required": true, "description": "The project slug", "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "description": "The project version", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "dependencies": { "type": "string" }, "name": { "type": "string", "description": "The name of the version", "example": "Version 1.0.1" }, "version": { "type": "string", "description": "The version number (must be unique for the project)", "example": "1.0.1" }, "release_type": { "type": "string", "description": "The release type", "example": "release" }, "release_date": { "type": "string", "format": "date", "description": "The release date", "example": "2024-01-20" }, "changelog": { "type": "string", "description": "The changelog for this version", "example": "Bug fixes" }, "tags[]": { "type": "array", "description": "Array of version tag slugs", "items": {} }, "files_to_remove[]": { "type": "array", "description": "Array of names of existing files to delete", "example": ["file1.txt", "file2.txt"], "items": {} }, "clean_existing_files": { "type": "boolean", "description": "Boolean to indicate if existing files should be deleted" }, "files[]": { "type": "array", "description": "Array of new files to upload", "items": { "type": "object", "description": "File to upload" } }, "dependencies[]": { "type": "array", "description": "Array of dependencies", "items": { "type": "object", "properties": { "project": { "type": "string", "description": "Project slug of the dependency" }, "version": { "type": "string", "description": "Version slug of the dependency" }, "type": { "type": "string", "description": "Dependency type", "default": "required" }, "external": { "type": "boolean", "description": "If the dependency is linked to a project in the platform or is external", "default": true } }, "required": [ "project", "type", "external" ] } } }, "required": [ "name", "version", "release_type", "release_date" ] } } } }, "responses": { "200": { "description": "`ProjectVersionResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProjectVersionResource" }, "message": { "type": "string", "const": "Version updated successfully" } }, "required": ["data", "message"] } } } }, "403": { "description": "An error\n\nAn error", "content": { "application/json": { "schema": { "anyOf": [ { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "example": "This project has been deactivated and versions cannot be edited." } }, "required": ["message"] }, { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "example": "You do not have permission to edit versions of this project." } }, "required": ["message"] } ] } } } }, "500": { "description": "An error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": ["message"] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "422": { "$ref": "#/components/responses/ValidationException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } }, "delete": { "operationId": "v1.project_version.destroy", "summary": "Delete a project version", "tags": ["ProjectVersion"], "parameters": [ { "name": "Authorization", "in": "header", "required": true, "description": "Bearer token", "schema": { "type": "string" }, "example": "Bearer {token}" }, { "name": "slug", "in": "path", "required": true, "description": "The project slug", "schema": { "type": "string" } }, { "name": "version", "in": "path", "required": true, "description": "The project version", "schema": { "type": "string" } } ], "responses": { "204": { "description": "No content" }, "403": { "description": "An error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview.", "example": "You do not have permission to delete versions of this project." } }, "required": ["message"] } } } }, "500": { "description": "An error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": ["message"] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/project_tags": { "get": { "operationId": "v1.project_tags", "description": "Returns a list of project tags", "summary": "List project tags", "tags": ["Tag"], "parameters": [ { "name": "plain", "in": "query", "description": "Whether to return the tags in a hierarchical structure or a flat list", "schema": {} }, { "name": "project_type", "in": "query", "description": "The project type to filter by (subtags of main tags with this project type will be included)", "schema": { "type": ["string", "null"], "default": null } } ], "responses": { "200": { "description": "Array of `ProjectTagResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectTagResource" } } }, "required": ["data"] } } } }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/v1/project_tag/{slug}": { "get": { "operationId": "v1.project_tag", "description": "Returns the project tag with the given slug", "summary": "Get a project tag", "tags": ["Tag"], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`ProjectTagResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProjectTagResource" } }, "required": ["data"] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" } } } }, "/v1/version_tags": { "get": { "operationId": "v1.version_tags", "description": "Returns a list of project version tags", "summary": "List project version tags", "tags": ["Tag"], "parameters": [ { "name": "plain", "in": "query", "description": "Whether to return the tags in a hierarchical structure or a flat list", "schema": {} }, { "name": "project_type", "in": "query", "description": "The project type to filter by (subtags of main tags with this project type will be included)", "schema": { "type": ["string", "null"], "default": null } } ], "responses": { "200": { "description": "Array of `ProjectVersionTagResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectVersionTagResource" } } }, "required": ["data"] } } } }, "422": { "$ref": "#/components/responses/ValidationException" } } } }, "/v1/version_tag/{slug}": { "get": { "operationId": "v1.version_tag", "description": "Returns the project version tag with the given slug", "summary": "Get a project version tag", "tags": ["Tag"], "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`ProjectVersionTagResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/ProjectVersionTagResource" } }, "required": ["data"] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" } } } }, "/test-token": { "get": { "operationId": "token.test", "description": "Returns basic information about the authenticated user and their token.", "summary": "Test endpoint to verify API token authentication", "tags": ["TokenTest"], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "const": "Token is valid" }, "user": { "type": "object", "properties": { "uername": { "type": "string" } }, "required": ["uername"] }, "token": { "type": "object", "properties": { "name": { "type": "string" }, "created_at": { "type": "string" }, "expires_at": { "type": "string" }, "last_used_at": { "type": "string" } }, "required": [ "name", "created_at", "expires_at", "last_used_at" ] }, "request_time": { "type": "string" } }, "required": [ "message", "user", "token", "request_time" ] } } } }, "401": { "$ref": "#/components/responses/AuthenticationException" } } } }, "/v1/user/{name}": { "get": { "operationId": "v1.user", "summary": "Get a user by name", "tags": ["User"], "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "`UserResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/UserResource" } }, "required": ["data"] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" } } } }, "/v1/user/{name}/projects": { "get": { "operationId": "v1.user.projects", "summary": "Get a user's projects", "tags": ["User"], "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Paginated set of `ProjectResource`", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectResource" } }, "links": { "type": "object", "properties": { "first": { "type": ["string", "null"] }, "last": { "type": ["string", "null"] }, "prev": { "type": ["string", "null"] }, "next": { "type": ["string", "null"] } }, "required": [ "first", "last", "prev", "next" ] }, "meta": { "type": "object", "properties": { "current_page": { "type": "integer", "minimum": 1 }, "from": { "type": ["integer", "null"], "minimum": 1 }, "last_page": { "type": "integer", "minimum": 1 }, "links": { "type": "array", "description": "Generated paginator links.", "items": { "type": "object", "properties": { "url": { "type": [ "string", "null" ] }, "label": { "type": "string" }, "active": { "type": "boolean" } }, "required": [ "url", "label", "active" ] } }, "path": { "type": ["string", "null"], "description": "Base path for paginator generated URLs." }, "per_page": { "type": "integer", "description": "Number of items shown per page.", "minimum": 0 }, "to": { "type": ["integer", "null"], "description": "Number of the last item in the slice.", "minimum": 1 }, "total": { "type": "integer", "description": "Total number of items being paginated.", "minimum": 0 } }, "required": [ "current_page", "from", "last_page", "links", "path", "per_page", "to", "total" ] } }, "required": ["data", "links", "meta"] } } } }, "404": { "$ref": "#/components/responses/ModelNotFoundException" } } } } }, "components": { "schemas": { "CollectionEntryReorderRequest": { "type": "object", "properties": { "entry_uids": { "type": "array", "items": { "type": "string" }, "minItems": 1 } }, "required": ["entry_uids"], "title": "CollectionEntryReorderRequest" }, "CollectionEntryResource": { "type": "object", "properties": { "uid": { "type": "string" }, "sort_order": { "type": "integer" }, "note": { "type": ["string", "null"] }, "project": { "anyOf": [ { "$ref": "#/components/schemas/ProjectResource" }, { "type": "null" } ] } }, "required": ["uid", "sort_order", "note"], "title": "CollectionEntryResource" }, "CollectionEntryStoreRequest": { "type": "object", "properties": { "project": { "type": "string" }, "note": { "type": ["string", "null"] }, "sort_order": { "type": ["integer", "null"], "minimum": 0 } }, "required": ["project"], "title": "CollectionEntryStoreRequest" }, "CollectionEntryUpdateNoteRequest": { "type": "object", "properties": { "note": { "type": ["string", "null"] } }, "title": "CollectionEntryUpdateNoteRequest" }, "CollectionQuickCreateRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": ["string", "null"] }, "project": { "type": "string" }, "note": { "type": ["string", "null"] } }, "required": ["name", "project"], "title": "CollectionQuickCreateRequest" }, "CollectionResource": { "type": "object", "properties": { "uid": { "type": "string" }, "name": { "type": "string" }, "description": { "type": ["string", "null"] }, "visibility": { "type": "string" }, "system_type": { "type": "string" }, "is_system": { "type": "boolean" }, "is_favorites": { "type": "boolean" }, "owner": { "type": "object", "properties": { "username": { "type": "string" } }, "required": ["username"] }, "hidden_share_token": { "type": ["string", "null"] }, "entries": { "type": "array", "items": { "$ref": "#/components/schemas/CollectionEntryResource" } }, "created_at": { "type": "string", "format": "datetime" }, "updated_at": { "type": "string", "format": "datetime" } }, "required": [ "uid", "name", "description", "visibility", "system_type", "is_system", "is_favorites", "created_at", "updated_at" ], "title": "CollectionResource" }, "CollectionStoreRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": ["string", "null"] }, "visibility": { "type": ["string", "null"], "enum": ["public", "private", "hidden"] } }, "required": ["name"], "title": "CollectionStoreRequest" }, "CollectionUpdateRequest": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": ["string", "null"] }, "visibility": { "type": "string", "enum": ["public", "private", "hidden"] } }, "title": "CollectionUpdateRequest" }, "DependencyType": { "type": "string", "enum": ["required", "optional", "embedded"], "title": "DependencyType" }, "ProjectFileResource": { "type": "object", "properties": { "name": { "type": "string" }, "size": { "type": "integer" }, "sha1": { "type": "string" }, "url": { "type": "string", "format": "url" } }, "required": ["name", "size", "sha1", "url"], "title": "ProjectFileResource" }, "ProjectResource": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "summary": { "type": "string" }, "description": { "type": ["string", "null"], "description": "Null in collection responses" }, "logo_url": { "type": "string" }, "website": { "type": ["string", "null"] }, "issues": { "type": ["string", "null"] }, "source": { "type": ["string", "null"] }, "type": { "type": "string" }, "tags": { "type": ["array", "null"], "description": "List of the slugs of the associated tags", "items": { "type": "string" } }, "status": { "type": "string", "description": "The status of the project, can be either 'active' or 'inactive'" }, "members": { "type": "array", "items": { "type": "object", "properties": { "username": { "type": "string" }, "role": { "type": "string" } }, "required": ["username", "role"] } }, "external_credits": { "type": ["array", "null"], "description": "External contributors declared by the project team.", "items": { "type": "object", "properties": { "name": { "type": "string" }, "role": { "type": "string" }, "url": { "type": ["string", "null"] } }, "required": ["name", "role", "url"] } }, "downloads": { "type": "integer" }, "favorite_count": { "type": "integer" }, "is_favorited": { "type": "boolean" }, "last_release_date": { "type": ["string", "null"], "format": "date" }, "version_count": { "type": "integer", "minimum": 0 }, "updated_at": { "type": ["string", "null"], "format": "datetime", "description": "Last update time of the project or one of its versions" }, "created_at": { "type": ["string", "null"], "format": "datetime" } }, "required": [ "name", "slug", "summary", "description", "logo_url", "website", "issues", "source", "status", "downloads", "favorite_count", "last_release_date", "updated_at", "created_at" ], "title": "ProjectResource" }, "ProjectTagResource": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "icon": { "type": "string" }, "tag_group": { "type": ["string", "null"] }, "project_types": { "type": "array", "description": "Array of project type slugs", "items": { "type": "string" } }, "sub_tags": { "type": "array", "description": "Unset when the request does not have the `plain` query parameter or is a single query", "items": { "$ref": "#/components/schemas/ProjectTagResource" } }, "main_tag": { "type": ["string", "null"] } }, "required": [ "name", "slug", "icon", "tag_group", "project_types", "main_tag" ], "title": "ProjectTagResource" }, "ProjectTypeResource": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "icon": { "type": "string" } }, "required": ["name", "slug", "icon"], "title": "ProjectTypeResource" }, "ProjectVersionDependencyResource": { "type": "object", "properties": { "project": { "type": "string", "description": "The project slug of the dependency" }, "version": { "type": ["string", "null"], "description": "The version of the dependency" }, "type": { "$ref": "#/components/schemas/DependencyType" }, "external": { "type": "boolean", "description": "Whether the dependency is external (not a project on this platform)" } }, "required": ["project", "version", "type", "external"], "title": "ProjectVersionDependencyResource" }, "ProjectVersionResource": { "type": "object", "properties": { "name": { "type": "string" }, "version": { "type": "string" }, "release_type": { "$ref": "#/components/schemas/ReleaseType" }, "release_date": { "type": "string", "format": "date" }, "changelog": { "type": ["string", "null"] }, "downloads": { "type": "integer" }, "tags": { "type": "array", "description": "List of version tag slugs", "items": { "type": "string" } }, "files": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectFileResource" } }, "dependencies": { "type": "array", "items": { "$ref": "#/components/schemas/ProjectVersionDependencyResource" } } }, "required": [ "name", "version", "release_type", "release_date", "changelog", "downloads", "tags" ], "title": "ProjectVersionResource" }, "ProjectVersionTagResource": { "type": "object", "properties": { "name": { "type": "string" }, "slug": { "type": "string" }, "icon": { "type": "string" }, "tag_group": { "type": ["string", "null"] }, "project_types": { "type": "array", "description": "Array of project type slugs", "items": { "type": "string" } }, "sub_tags": { "type": "array", "description": "Unset when the request does not have the `plain` query parameter or is a single query", "items": { "$ref": "#/components/schemas/ProjectVersionTagResource" } }, "main_tag": { "type": ["string", "null"] } }, "required": [ "name", "slug", "icon", "tag_group", "project_types", "main_tag" ], "title": "ProjectVersionTagResource" }, "ReleaseType": { "type": "string", "enum": ["alpha", "beta", "rc", "prerelease", "release"], "title": "ReleaseType" }, "UserResource": { "type": "object", "properties": { "username": { "type": "string" }, "bio": { "type": ["string", "null"] }, "avatar": { "type": ["string", "null"], "format": "url" }, "created_at": { "type": "string", "format": "date" } }, "required": ["username", "bio", "avatar", "created_at"], "title": "UserResource" } }, "responses": { "AuthenticationException": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": ["message"] } } } }, "ValidationException": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": ["message", "errors"] } } } }, "ModelNotFoundException": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": ["message"] } } } }, "AuthorizationException": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": ["message"] } } } } } } }