# Projects Download the [specification](https://api.kpnthings.com/openapi-specifications/projects) ## GET /projects/{projectId} > Retrieve a project by ID ```json {"openapi":"3.1.0","info":{"title":"Things Projects API","version":"0.8.0"},"servers":[{"url":"https://api.kpnthings.com","description":"Things API Environment"}],"security":[{"BearerAuth":["project.read"]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"schemas":{"Project":{"type":"object","description":"Project in KPN Things that serves as a container for devices, destinations, flows and metadata","properties":{"id":{"type":"string","format":"uuid","description":"The entity ID","readOnly":true},"clientId":{"type":"string","format":"uuid","description":"ID of owning client"},"createdAt":{"type":"string","format":"date-time","description":"The timestamp when the project is created in the system.","readOnly":true},"createdBy":{"type":"string","description":"The user who created the project.","readOnly":true},"modifiedAt":{"type":"string","format":"date-time","description":"The timestamp when the project is last modified in the system.","readOnly":true},"modifiedBy":{"type":"string","description":"The user who last modified the project.","readOnly":true},"name":{"allOf":[{"$ref":"#/components/schemas/NonBlankString"},{"type":"string","description":"The project name"}]},"description":{"allOf":[{"$ref":"#/components/schemas/NonBlankString"},{"type":"string","description":"A short description of the project"}]},"definition":{"$ref":"#/components/schemas/ProjectDefinition"}},"required":["clientId","definition","id","name"],"title":"Project"},"NonBlankString":{"type":"string","description":"Must not be empty or contain only whitespace.","minLength":1,"pattern":".*\\S.*"},"ProjectDefinition":{"type":"object","description":"Describes the type and constraints of a KPN Things Project","properties":{"type":{"type":"string","description":"The project type. Known values include: ASSET_INSURANCE_E2E, ASSET_TRACKING_E2E, ASSET_TRACKING_RESELLER, CONDITION_MONITORING_E2E, CUSTOM, CUSTOM_RESELLER, EXPLORER, EXPLORER_WITH_M2M, FILL_LEVEL_E2E, FILL_LEVEL_RESELLER, FREEMIUM, FREEMIUM_WITH_M2M, MODULAR, MODULAR_RESTRICTED, TAILORED and UNLIMITED"},"maxDevices":{"type":"integer","format":"int32","description":"The maximum number of devices that can be registered under a project. -1 means unbounded."},"maxDestinations":{"type":"integer","format":"int32","description":"The maximum number of destinations that can be registered under a project. -1 means unbounded."},"maxDeviceGroups":{"type":"integer","format":"int32","description":"The maximum number of device groups that can be registered under a project. -1 means unbounded."}},"required":["type"],"title":"ProjectDefinition"}}},"paths":{"/projects/{projectId}":{"get":{"summary":"Retrieve a project by ID","operationId":"getProject","parameters":[{"name":"projectId","in":"path","description":"Project identifier","required":true,"style":"simple","schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"The project","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Project"}}}}}}}}} ``` ## Retrieve projects, filtered by search term and / or client ID > Retrieve all projects that match the query parameters given. If a search parameter is provided, projects whose name or description (partially) match are returned. ```json {"openapi":"3.1.0","info":{"title":"Things Projects API","version":"0.8.0"},"servers":[{"url":"https://api.kpnthings.com","description":"Things API Environment"}],"security":[{"BearerAuth":["project.read"]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT"}},"parameters":{"cursor":{"name":"cursor","in":"query","description":"String that encodes all necessary information to retrieve a page.","style":"form","explode":true,"schema":{"type":"string","format":"cursor"}},"limit":{"name":"limit","in":"query","description":"Limit the number of results (per page).","style":"form","explode":true,"schema":{"type":"integer","default":50}},"sort":{"name":"sort","in":"query","description":"Sorting fields separated by comma. Default order is Ascending (ASC), minus(-) should be used in front of field name for Descending (DESC) order.","style":"form","explode":true,"schema":{"type":"string"}}},"schemas":{"PageOfProjects":{"type":"object","allOf":[{"$ref":"#/components/schemas/Page"},{"properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Project"}}}}],"description":"A paginated list of projects","title":"PageOfProjects"},"Page":{"type":"object","description":"Page of items","properties":{"items":{"type":"array","items":{}},"next":{"type":"string","format":"uri","description":"Pagination link pointing to the next page. Only provided when not at the last page."},"prev":{"type":"string","format":"uri","description":"Pagination link pointing to the previous page. Only provided when not at the first page."}},"required":["items"],"title":"Page"},"Project":{"type":"object","description":"Project in KPN Things that serves as a container for devices, destinations, flows and metadata","properties":{"id":{"type":"string","format":"uuid","description":"The entity ID","readOnly":true},"clientId":{"type":"string","format":"uuid","description":"ID of owning client"},"createdAt":{"type":"string","format":"date-time","description":"The timestamp when the project is created in the system.","readOnly":true},"createdBy":{"type":"string","description":"The user who created the project.","readOnly":true},"modifiedAt":{"type":"string","format":"date-time","description":"The timestamp when the project is last modified in the system.","readOnly":true},"modifiedBy":{"type":"string","description":"The user who last modified the project.","readOnly":true},"name":{"allOf":[{"$ref":"#/components/schemas/NonBlankString"},{"type":"string","description":"The project name"}]},"description":{"allOf":[{"$ref":"#/components/schemas/NonBlankString"},{"type":"string","description":"A short description of the project"}]},"definition":{"$ref":"#/components/schemas/ProjectDefinition"}},"required":["clientId","definition","id","name"],"title":"Project"},"NonBlankString":{"type":"string","description":"Must not be empty or contain only whitespace.","minLength":1,"pattern":".*\\S.*"},"ProjectDefinition":{"type":"object","description":"Describes the type and constraints of a KPN Things Project","properties":{"type":{"type":"string","description":"The project type. Known values include: ASSET_INSURANCE_E2E, ASSET_TRACKING_E2E, ASSET_TRACKING_RESELLER, CONDITION_MONITORING_E2E, CUSTOM, CUSTOM_RESELLER, EXPLORER, EXPLORER_WITH_M2M, FILL_LEVEL_E2E, FILL_LEVEL_RESELLER, FREEMIUM, FREEMIUM_WITH_M2M, MODULAR, MODULAR_RESTRICTED, TAILORED and UNLIMITED"},"maxDevices":{"type":"integer","format":"int32","description":"The maximum number of devices that can be registered under a project. -1 means unbounded."},"maxDestinations":{"type":"integer","format":"int32","description":"The maximum number of destinations that can be registered under a project. -1 means unbounded."},"maxDeviceGroups":{"type":"integer","format":"int32","description":"The maximum number of device groups that can be registered under a project. -1 means unbounded."}},"required":["type"],"title":"ProjectDefinition"},"Problem":{"type":"object","description":"Error information details","properties":{"type":{"type":"string","format":"uri-reference","default":"about:blank","description":"A URI reference that uniquely identifies the problem type only in the\ncontext of the provided API. Opposed to the specification in RFC-9457,\nit is neither recommended to be dereferenceable and point to a\nhuman-readable documentation nor globally unique for the problem type."},"title":{"type":"string","description":"A short summary of the problem type. Written in English and readable\nfor engineers, usually not suited for non technical stakeholders and\nnot localized."},"status":{"type":"integer","format":"int32","description":"The HTTP status code generated by the origin server for this occurrence\nof the problem.","exclusiveMaximum":600,"minimum":100},"detail":{"type":"string","description":"A human readable explanation specific to this occurrence of the\nproblem that is helpful to locate the problem and give advice on how\nto proceed. Written in English and readable for engineers, usually not\nsuited for non technical stakeholders and not localized."},"instance":{"type":"string","format":"uri-reference","description":"A URI reference that identifies the specific occurrence of the problem,\ne.g. by adding a fragment identifier or sub-path to the problem type.\nMay be used to locate the root of this problem in the source code."}},"title":"Problem"}},"responses":{"badRequest":{"description":"Request is missing required information or invalid","content":{"application/problem+json":{"schema":{"$ref":"#/components/schemas/Problem"}}}}}},"paths":{"/projects":{"get":{"summary":"Retrieve projects, filtered by search term and / or client ID","description":"Retrieve all projects that match the query parameters given. If a search parameter is provided, projects whose name or description (partially) match are returned.","operationId":"searchProjects","parameters":[{"$ref":"#/components/parameters/cursor"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/sort"},{"name":"q","in":"query","description":"Include only projects whose name or description contain the search term. Matching is done case-insensitively.","style":"form","explode":true,"schema":{"type":"string","minLength":1}},{"name":"clientId","in":"query","description":"Include only projects owned by the client matching clientId.","style":"form","explode":true,"schema":{"type":"string","format":"uuid"}},{"name":"createdBefore","in":"query","description":"Include only projects created before the provided date and time. The date-time must be in ISO 8601 format.","style":"form","explode":true,"schema":{"type":"string","format":"date-time"}},{"name":"createdSince","in":"query","description":"Include only projects created at or after the provided date and time. The date-time must be in ISO 8601 format.","style":"form","explode":true,"schema":{"type":"string","format":"date-time"}},{"name":"modifiedBefore","in":"query","description":"Include only projects modified before the provided date and time. The date-time must be in ISO 8601 format.","style":"form","explode":true,"schema":{"type":"string","format":"date-time"}},{"name":"modifiedSince","in":"query","description":"Include only projects modified at or after the provided date and time. The date-time must be in ISO 8601 format.","style":"form","explode":true,"schema":{"type":"string","format":"date-time"}}],"responses":{"200":{"description":"Page of filtered projects. Only projects that are accessible to the caller are returned.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PageOfProjects"}}}},"400":{"$ref":"#/components/responses/badRequest"}}}}}} ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.kpnthings.com/kpn-things/general-functions/apis/projects.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.