{
  "aid": "craftboxx.de:main-1.1.0",
  "name": "Craftboxx API Documentation",
  "type": "Index",
  "description": "\nThis document provides a comprehensive guide to integrating with the Craftboxx API. It is designed for developers looking to build applications and services that interact with the Craftboxx platform.\n\n### Authentication\n\nTo use the API, you must first generate a Bearer access token.\n\n1. Obtain a Token: Send a `POST` request with your employee credentials (email and password) to the `/auth/create-token` endpoint.\n2. Authorize Requests: Include the obtained token in the `Authorization` header for every subsequent API call. The header should be formatted as follows:\n   `Authorization: Bearer <YOUR_ACCESS_TOKEN>`\n\nYour API access is governed by the same permissions you have in the Craftboxx Planner. If your token is invalid or expired, the API will return a `401 Unauthorized` status code.\n\n### API Principles\n\nThis API largely follows RESTful design principles. Endpoints are organized around resources, and it uses standard HTTP methods for operations.\n\n### Requests for Resource Collections\n\nWhen fetching a list of resources (e.g., `/articles`, `/projects`), you can use a variety of query parameters to refine the results.\n\n#### Filtering and Searching\n\n- Generic Search (`q`): Performs a broad search across all relevant fields of a resource.\n  - Example: `/articles?q=Bosch Akkuschrauber`\n- Filter by ID (`id[]`): Retrieves specific resources by their unique IDs.\n  - Example (Single): `/articles?id=50`\n  - Example (Multiple): `/articles?id[]=50&id[]=51`\n- Exclude by ID (`exclude[]`): Excludes specific resources from the results.\n  - Example (Single): `/articles?exclude=50`\n  - Example (Multiple): `/articles?exclude[]=50&exclude[]=51`\n- Attribute Filtering: Filters results based on specific attribute values. This supports exact matches, SQL-like `LIKE` searches with the `%` wildcard, and multiple values using array syntax.\n  - Example (LIKE search): `/articles?manufacturer=Bosch%`\n  - Example (Multiple values): `/articles?manufacturer[]=Bosch&manufacturer[]=Makita`\n- Comparison Operators: For more precise filtering on attributes like dates or numbers, you can specify a comparison operator.\n  - Example (Date greater than or equal to): `date_comparison=%3E%3D&date=2025-05-01` (where `%3E%3D` is the URL-encoded version of `>=`)\n  - Allowed Operators: `LIKE`, `NOT LIKE`, `=`, `!=`, `>`, `>=`, `<`, `<=`\n- Date Formats: While many date formats are accepted, the recommended format is ISO-8601 with a timezone, such as `2025-01-01T12:00:00+01:00`.\n\n#### Sorting\n\n- Sort Order (`order_by` & `order_direction`): Sorts the result set by a specific attribute in either ascending or descending order.\n  - Example: `/articles?order_by=manufacturer&order_direction=desc`\n\n#### Pagination\n\n- Paginating Results (`per_page` & `page`): Controls the number of items per page and which page of results to return.\n  - Example: `/articles?per_page=25&page=3`\n\n#### Working with Relationships\n\nRelations are by default not included in the response. They has to be explicitly loaded. You have the following options:\n \n- Load Relations (`with`): Eager-loads related resources to include them in the response, reducing the need for subsequent API calls.\n  - Example (Single): `/articles?with=assignments`\n  - Example (Multiple): `/employees?with[]=assignments&with[]=projects`\n- Filter Fields (`only`): Returns only the specified attributes of a resource, supporting nested structures with dot notation.\n   - Example (Single): `/articles?only=id`\n   - Example (Multiple): `/articles?only[]=id&only[]=name`\n   - Example (Nested): `/assignments?with=project&only[]=id&only[]=project.id`\n- Filter by Relations: Retrieves resources that are associated with another specific resource.\n   - Example (Get all articles for assignment 50): `/articles?assignments=50`\n- Count Relations (`count`): Returns a count of related resources instead of the resources themselves.\n   - Example (Single): `/assignments?with_count=articles`\n   - Example (Multiple): `/assignments?with_count[]=articles&with_count[]=employees`\n- Min / Max value of a Relation: Retrieves the minimum or maximum value of a relation.\n   - Example (Single): `/projects?with_min=assignment.start&with_max=assignment.end`\n   - Example (Multiple): `/projects?with_min[]=assignment.start&with_min[]=documentations.documented_on&with_max[]=assignment.end&with_max[]=documentations.documented_on`\n- Sum of a Relation: Retrieves the sum of a relation.\n   - Example (Single): `/assignment?with_sum=billable_timesheet_activites.duration_seconds`\n   - Example (Multiple): `/assignment?with_sum[]=billable_timesheet_activites.duration_seconds`\n- Filter by Relational Properties: Filters based on the properties of a related model. The model and property are separated by a hyphen.\n   - Example (Find projects by a customer's customer number): `/projects?customer-customer_number=123`\n\nNote: For a complete list of filterable attributes and relations for a resource, refer to the attributes available in its corresponding `GET` Schema.\n\n### Requests for a Single Resource\n\nTo retrieve a single resource, make a `GET` request to the resource endpoint with its unique ID.\n\n- Example (Single): `/articles/50`\n- Filter Fields (`only`): Returns only the specified attributes of a resource (Same as the `only` parameter for resource collections)\n    - Example (Single): `/articles/50?only=id`\n    - Example (Multiple): `/articles/50?only[]=id&only[]=name`\n- Load Relations (`load`): You can use `load` for eager-loading related resources (Similar to the `with` parameter for resource collections)\n    - Example (Single): `/timesheets/123?load[]=employee`\n    - Example (Multiple): `/timesheets/123?load[]=activities&load[]=employee`\n- If a resource does not exist, the API will return a `404 Not Found` error.\n\n### HTTP Methods Overview\n\n| Method   | Action                                      | Successful Response | Error Responses                                |\n| :------- | :------------------------------------------ | :------------------ | :--------------------------------------------- |\n| GET      | Retrieves one or a collection of resources. | `200 OK`            | `401 Unauthorized`, `404 Not Found`            |\n| POST     | Creates a new resource.                     | `201 Created`       | `401 Unauthorized`, `422 Unprocessable Entity` |\n| PUT      | Updates an existing resource.               | `200 OK`            | `401 Unauthorized`, `404 Not Found`, `422 Unprocessable Entity` |\n| DELETE   | Deletes a resource.                         | `200 OK`            | `401 Unauthorized`, `404 Not Found`            |\n\n### Common Status Codes\n\n| Code | Meaning                  | Description                                                                 |\n| :--- | :----------------------- | :-------------------------------------------------------------------------- |\n| 200  | OK                       | The request was successful.                                                 |\n| 201  | Created                  | The resource was successfully created (used for `POST` requests).           |\n| 401  | Unauthorized             | The request lacks valid authentication credentials.                         |\n| 404  | Not Found                | The requested resource could not be found.                                  |\n| 422  | Unprocessable Entity     | The request was well-formed, but contains semantic errors (e.g., validation failed). |\n| 500  | Internal Server Error    | An unexpected error occurred on the server, often when a requested relation does not exist. |\n",
  "url": "https://raw.githubusercontent.com/jentic/jentic-public-apis/refs/heads/main/apis/openapi/craftboxx.de/main/1.1.0/apis.json",
  "tags": [
    "craftboxx.de",
    "main"
  ],
  "created": "2026-04-09",
  "modified": "2026-04-09",
  "specificationVersion": "0.19",
  "access": "3rd-Party",
  "maintainers": [
    {
      "FN": "Jentic",
      "X-github": "jentic",
      "url": "https://github.com/jentic"
    }
  ],
  "apis": [
    {
      "aid": "craftboxx.de:main-1.1.0",
      "name": "Craftboxx API Documentation",
      "description": "\nThis document provides a comprehensive guide to integrating with the Craftboxx API. It is designed for developers looking to build applications and services that interact with the Craftboxx platform.\n\n### Authentication\n\nTo use the API, you must first generate a Bearer access token.\n\n1. Obtain a Token: Send a `POST` request with your employee credentials (email and password) to the `/auth/create-token` endpoint.\n2. Authorize Requests: Include the obtained token in the `Authorization` header for every subsequent API call. The header should be formatted as follows:\n   `Authorization: Bearer <YOUR_ACCESS_TOKEN>`\n\nYour API access is governed by the same permissions you have in the Craftboxx Planner. If your token is invalid or expired, the API will return a `401 Unauthorized` status code.\n\n### API Principles\n\nThis API largely follows RESTful design principles. Endpoints are organized around resources, and it uses standard HTTP methods for operations.\n\n### Requests for Resource Collections\n\nWhen fetching a list of resources (e.g., `/articles`, `/projects`), you can use a variety of query parameters to refine the results.\n\n#### Filtering and Searching\n\n- Generic Search (`q`): Performs a broad search across all relevant fields of a resource.\n  - Example: `/articles?q=Bosch Akkuschrauber`\n- Filter by ID (`id[]`): Retrieves specific resources by their unique IDs.\n  - Example (Single): `/articles?id=50`\n  - Example (Multiple): `/articles?id[]=50&id[]=51`\n- Exclude by ID (`exclude[]`): Excludes specific resources from the results.\n  - Example (Single): `/articles?exclude=50`\n  - Example (Multiple): `/articles?exclude[]=50&exclude[]=51`\n- Attribute Filtering: Filters results based on specific attribute values. This supports exact matches, SQL-like `LIKE` searches with the `%` wildcard, and multiple values using array syntax.\n  - Example (LIKE search): `/articles?manufacturer=Bosch%`\n  - Example (Multiple values): `/articles?manufacturer[]=Bosch&manufacturer[]=Makita`\n- Comparison Operators: For more precise filtering on attributes like dates or numbers, you can specify a comparison operator.\n  - Example (Date greater than or equal to): `date_comparison=%3E%3D&date=2025-05-01` (where `%3E%3D` is the URL-encoded version of `>=`)\n  - Allowed Operators: `LIKE`, `NOT LIKE`, `=`, `!=`, `>`, `>=`, `<`, `<=`\n- Date Formats: While many date formats are accepted, the recommended format is ISO-8601 with a timezone, such as `2025-01-01T12:00:00+01:00`.\n\n#### Sorting\n\n- Sort Order (`order_by` & `order_direction`): Sorts the result set by a specific attribute in either ascending or descending order.\n  - Example: `/articles?order_by=manufacturer&order_direction=desc`\n\n#### Pagination\n\n- Paginating Results (`per_page` & `page`): Controls the number of items per page and which page of results to return.\n  - Example: `/articles?per_page=25&page=3`\n\n#### Working with Relationships\n\nRelations are by default not included in the response. They has to be explicitly loaded. You have the following options:\n \n- Load Relations (`with`): Eager-loads related resources to include them in the response, reducing the need for subsequent API calls.\n  - Example (Single): `/articles?with=assignments`\n  - Example (Multiple): `/employees?with[]=assignments&with[]=projects`\n- Filter Fields (`only`): Returns only the specified attributes of a resource, supporting nested structures with dot notation.\n   - Example (Single): `/articles?only=id`\n   - Example (Multiple): `/articles?only[]=id&only[]=name`\n   - Example (Nested): `/assignments?with=project&only[]=id&only[]=project.id`\n- Filter by Relations: Retrieves resources that are associated with another specific resource.\n   - Example (Get all articles for assignment 50): `/articles?assignments=50`\n- Count Relations (`count`): Returns a count of related resources instead of the resources themselves.\n   - Example (Single): `/assignments?with_count=articles`\n   - Example (Multiple): `/assignments?with_count[]=articles&with_count[]=employees`\n- Min / Max value of a Relation: Retrieves the minimum or maximum value of a relation.\n   - Example (Single): `/projects?with_min=assignment.start&with_max=assignment.end`\n   - Example (Multiple): `/projects?with_min[]=assignment.start&with_min[]=documentations.documented_on&with_max[]=assignment.end&with_max[]=documentations.documented_on`\n- Sum of a Relation: Retrieves the sum of a relation.\n   - Example (Single): `/assignment?with_sum=billable_timesheet_activites.duration_seconds`\n   - Example (Multiple): `/assignment?with_sum[]=billable_timesheet_activites.duration_seconds`\n- Filter by Relational Properties: Filters based on the properties of a related model. The model and property are separated by a hyphen.\n   - Example (Find projects by a customer's customer number): `/projects?customer-customer_number=123`\n\nNote: For a complete list of filterable attributes and relations for a resource, refer to the attributes available in its corresponding `GET` Schema.\n\n### Requests for a Single Resource\n\nTo retrieve a single resource, make a `GET` request to the resource endpoint with its unique ID.\n\n- Example (Single): `/articles/50`\n- Filter Fields (`only`): Returns only the specified attributes of a resource (Same as the `only` parameter for resource collections)\n    - Example (Single): `/articles/50?only=id`\n    - Example (Multiple): `/articles/50?only[]=id&only[]=name`\n- Load Relations (`load`): You can use `load` for eager-loading related resources (Similar to the `with` parameter for resource collections)\n    - Example (Single): `/timesheets/123?load[]=employee`\n    - Example (Multiple): `/timesheets/123?load[]=activities&load[]=employee`\n- If a resource does not exist, the API will return a `404 Not Found` error.\n\n### HTTP Methods Overview\n\n| Method   | Action                                      | Successful Response | Error Responses                                |\n| :------- | :------------------------------------------ | :------------------ | :--------------------------------------------- |\n| GET      | Retrieves one or a collection of resources. | `200 OK`            | `401 Unauthorized`, `404 Not Found`            |\n| POST     | Creates a new resource.                     | `201 Created`       | `401 Unauthorized`, `422 Unprocessable Entity` |\n| PUT      | Updates an existing resource.               | `200 OK`            | `401 Unauthorized`, `404 Not Found`, `422 Unprocessable Entity` |\n| DELETE   | Deletes a resource.                         | `200 OK`            | `401 Unauthorized`, `404 Not Found`            |\n\n### Common Status Codes\n\n| Code | Meaning                  | Description                                                                 |\n| :--- | :----------------------- | :-------------------------------------------------------------------------- |\n| 200  | OK                       | The request was successful.                                                 |\n| 201  | Created                  | The resource was successfully created (used for `POST` requests).           |\n| 401  | Unauthorized             | The request lacks valid authentication credentials.                         |\n| 404  | Not Found                | The requested resource could not be found.                                  |\n| 422  | Unprocessable Entity     | The request was well-formed, but contains semantic errors (e.g., validation failed). |\n| 500  | Internal Server Error    | An unexpected error occurred on the server, often when a requested relation does not exist. |\n",
      "image": "",
      "baseURL": "https://api.craftboxx.de",
      "humanURL": "https://github.com/jentic/jentic-public-apis/tree/main/apis/openapi/craftboxx.de/main/1.1.0",
      "version": "1.1.0",
      "tags": [
        "craftboxx.de",
        "main"
      ],
      "properties": [
        {
          "type": "OpenAPI",
          "name": "OpenAPI definition",
          "url": "https://raw.githubusercontent.com/jentic/jentic-public-apis/refs/heads/main/apis/openapi/craftboxx.de/main/1.1.0/openapi.json",
          "mediaType": "application/openapi+json"
        },
        {
          "type": "GitHubRepo",
          "url": "https://github.com/jentic/jentic-public-apis/tree/main/apis/openapi/craftboxx.de/main/1.1.0"
        }
      ]
    }
  ]
}