# Organizations
Organization management endpoints
## Get current organization
> Retrieve information about the organization associated with the authentication token
```json
{"openapi":"3.0.3","info":{"title":"Blynk Platform API","version":"1.0.0"},"tags":[{"name":"Organizations","description":"Organization management endpoints"}],"servers":[{"url":"https://{server_address}","description":"Blynk Server","variables":{"server_address":{"default":"blynk.cloud","description":"Your Blynk server domain"}}}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth2 Bearer token obtained from authentication endpoint"}},"schemas":{"Organization":{"type":"object","properties":{"id":{"type":"integer","format":"int32","description":"Organization unique identifier"},"name":{"type":"string","description":"Organization name"},"description":{"type":"string","description":"Organization description"},"parentOrganizationId":{"type":"integer","format":"int32","description":"Parent organization ID (for hierarchical structure)"},"tz":{"type":"string","description":"A timezone, associated with the organization"},"unitSystem":{"type":"string","enum":["IMPERIAL","METRIC"],"description":"Unit system used in the organization."},"phoneNumber":{"type":"string","description":"Phone number, associated with the organization."},"address":{"$ref":"#/components/schemas/Address"},"lastModifiedTs":{"type":"integer","format":"int64","description":"Timestamp, indicating the time, when the organization was modified last time (Unix epoch milliseconds)"}},"required":["id","name","tz","lastModifiedTs"]},"Address":{"type":"object","properties":{"fullAddress":{"type":"string","maxLength":512,"description":"Full address"},"country":{"type":"string","maxLength":74,"description":"Country name"},"city":{"type":"string","maxLength":50,"description":"City name"},"state":{"type":"string","maxLength":40,"description":"State or province"},"zip":{"type":"string","maxLength":12,"description":"Postal code"}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string","description":"Error message"}},"required":["message"]}},"required":["error"]}}},"paths":{"/api/v1/organization/profile":{"get":{"tags":["Organizations"],"summary":"Get current organization","description":"Retrieve information about the organization associated with the authentication token","operationId":"getOwnOrganization","responses":{"200":{"description":"Organization details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Organization"}}}},"403":{"description":"Forbidden"},"429":{"description":"Too many requests"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
## Search organizations
> Search for organizations by the provided query.\
> \
> Required permissions, when user-scoped authentication is used: \`ORG\_VIEW\`.
```json
{"openapi":"3.0.3","info":{"title":"Blynk Platform API","version":"1.0.0"},"tags":[{"name":"Organizations","description":"Organization management endpoints"}],"servers":[{"url":"https://{server_address}","description":"Blynk Server","variables":{"server_address":{"default":"blynk.cloud","description":"Your Blynk server domain"}}}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth2 Bearer token obtained from authentication endpoint"}},"schemas":{"Organization":{"type":"object","properties":{"id":{"type":"integer","format":"int32","description":"Organization unique identifier"},"name":{"type":"string","description":"Organization name"},"description":{"type":"string","description":"Organization description"},"parentOrganizationId":{"type":"integer","format":"int32","description":"Parent organization ID (for hierarchical structure)"},"tz":{"type":"string","description":"A timezone, associated with the organization"},"unitSystem":{"type":"string","enum":["IMPERIAL","METRIC"],"description":"Unit system used in the organization."},"phoneNumber":{"type":"string","description":"Phone number, associated with the organization."},"address":{"$ref":"#/components/schemas/Address"},"lastModifiedTs":{"type":"integer","format":"int64","description":"Timestamp, indicating the time, when the organization was modified last time (Unix epoch milliseconds)"}},"required":["id","name","tz","lastModifiedTs"]},"Address":{"type":"object","properties":{"fullAddress":{"type":"string","maxLength":512,"description":"Full address"},"country":{"type":"string","maxLength":74,"description":"Country name"},"city":{"type":"string","maxLength":50,"description":"City name"},"state":{"type":"string","maxLength":40,"description":"State or province"},"zip":{"type":"string","maxLength":12,"description":"Postal code"}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string","description":"Error message"}},"required":["message"]}},"required":["error"]}}},"paths":{"/api/v1/organization/search":{"get":{"tags":["Organizations"],"summary":"Search organizations","description":"Search for organizations by the provided query.\n\nRequired permissions, when user-scoped authentication is used: `ORG_VIEW`.\n","operationId":"searchOrganizations","parameters":[{"name":"query","in":"query","required":true,"schema":{"type":"string","maxLength":255},"description":"Search query string"},{"name":"sortBy","in":"query","schema":{"type":"string"},"description":"Field to sort by"},{"name":"sortOrder","in":"query","schema":{"type":"string","enum":["ASC","DESC"],"default":"ASC"},"description":"Sort order"},{"name":"page","in":"query","schema":{"type":"integer","format":"int32","default":0,"minimum":0},"description":"Page number (0-indexed)"},{"name":"size","in":"query","schema":{"type":"integer","format":"int32","default":50,"minimum":1,"maximum":1000},"description":"Page size (max 1000)"}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"array","items":{"$ref":"#/components/schemas/Organization"},"description":"Array of matching organizations"},"totalElements":{"type":"integer","format":"int64","description":"Total amount of organizations, available to fetch."}},"required":["content","totalElements"]}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden"},"429":{"description":"Too many requests"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
## Get organization by ID
> Retrieve information about a specific organization.\
> \
> Required permissions, when user-scoped authentication is used: \`ORG\_VIEW\`.
```json
{"openapi":"3.0.3","info":{"title":"Blynk Platform API","version":"1.0.0"},"tags":[{"name":"Organizations","description":"Organization management endpoints"}],"servers":[{"url":"https://{server_address}","description":"Blynk Server","variables":{"server_address":{"default":"blynk.cloud","description":"Your Blynk server domain"}}}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth2 Bearer token obtained from authentication endpoint"}},"schemas":{"Organization":{"type":"object","properties":{"id":{"type":"integer","format":"int32","description":"Organization unique identifier"},"name":{"type":"string","description":"Organization name"},"description":{"type":"string","description":"Organization description"},"parentOrganizationId":{"type":"integer","format":"int32","description":"Parent organization ID (for hierarchical structure)"},"tz":{"type":"string","description":"A timezone, associated with the organization"},"unitSystem":{"type":"string","enum":["IMPERIAL","METRIC"],"description":"Unit system used in the organization."},"phoneNumber":{"type":"string","description":"Phone number, associated with the organization."},"address":{"$ref":"#/components/schemas/Address"},"lastModifiedTs":{"type":"integer","format":"int64","description":"Timestamp, indicating the time, when the organization was modified last time (Unix epoch milliseconds)"}},"required":["id","name","tz","lastModifiedTs"]},"Address":{"type":"object","properties":{"fullAddress":{"type":"string","maxLength":512,"description":"Full address"},"country":{"type":"string","maxLength":74,"description":"Country name"},"city":{"type":"string","maxLength":50,"description":"City name"},"state":{"type":"string","maxLength":40,"description":"State or province"},"zip":{"type":"string","maxLength":12,"description":"Postal code"}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string","description":"Error message"}},"required":["message"]}},"required":["error"]}}},"paths":{"/api/v1/organization":{"get":{"tags":["Organizations"],"summary":"Get organization by ID","description":"Retrieve information about a specific organization.\n\nRequired permissions, when user-scoped authentication is used: `ORG_VIEW`.\n","operationId":"getOrganization","parameters":[{"name":"orgId","in":"query","required":true,"schema":{"type":"integer","format":"int32"},"description":"Organization ID"}],"responses":{"200":{"description":"Organization details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Organization"}}}},"403":{"description":"Unauthorized - Invalid or missing token"},"404":{"description":"Organization not found or access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many requests - Rate limit exceeded"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
## Delete organization
> Delete an organization. Users and other resources in the organization are being deleted automatically.\
> \
> The following organizations cannot be deleted:\
> \- The organization used for authentication (your own organization)\
> \- The root (super) organization\
> \- The Clients group organization\
> \- The Partners group organization\
> \- Organizations that have sub-organizations\
> \- Organizations that have devices\
> \
> Required permissions, when user-scoped authentication is used: \`ORG\_DELETE\`.
```json
{"openapi":"3.0.3","info":{"title":"Blynk Platform API","version":"1.0.0"},"tags":[{"name":"Organizations","description":"Organization management endpoints"}],"servers":[{"url":"https://{server_address}","description":"Blynk Server","variables":{"server_address":{"default":"blynk.cloud","description":"Your Blynk server domain"}}}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth2 Bearer token obtained from authentication endpoint"}},"schemas":{"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string","description":"Error message"}},"required":["message"]}},"required":["error"]}}},"paths":{"/api/v1/organization":{"delete":{"tags":["Organizations"],"summary":"Delete organization","description":"Delete an organization. Users and other resources in the organization are being deleted automatically.\n\nThe following organizations cannot be deleted:\n- The organization used for authentication (your own organization)\n- The root (super) organization\n- The Clients group organization\n- The Partners group organization\n- Organizations that have sub-organizations\n- Organizations that have devices\n\nRequired permissions, when user-scoped authentication is used: `ORG_DELETE`.\n","operationId":"deleteOrganization","parameters":[{"name":"orgId","in":"query","required":true,"schema":{"type":"integer","format":"int32"},"description":"Organization ID"}],"responses":{"204":{"description":"Organization deleted successfully"},"400":{"description":"Some of the validations have not been passed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Unauthorized - Invalid or missing token"},"404":{"description":"Organization not found or access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many requests"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
## Create a new organization
> Create a new organization.\
> \
> Required permissions, when user-scoped authentication is used: \`ORG\_CREATE\`.
```json
{"openapi":"3.0.3","info":{"title":"Blynk Platform API","version":"1.0.0"},"tags":[{"name":"Organizations","description":"Organization management endpoints"}],"servers":[{"url":"https://{server_address}","description":"Blynk Server","variables":{"server_address":{"default":"blynk.cloud","description":"Your Blynk server domain"}}}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth2 Bearer token obtained from authentication endpoint"}},"schemas":{"Organization":{"type":"object","properties":{"id":{"type":"integer","format":"int32","description":"Organization unique identifier"},"name":{"type":"string","description":"Organization name"},"description":{"type":"string","description":"Organization description"},"parentOrganizationId":{"type":"integer","format":"int32","description":"Parent organization ID (for hierarchical structure)"},"tz":{"type":"string","description":"A timezone, associated with the organization"},"unitSystem":{"type":"string","enum":["IMPERIAL","METRIC"],"description":"Unit system used in the organization."},"phoneNumber":{"type":"string","description":"Phone number, associated with the organization."},"address":{"$ref":"#/components/schemas/Address"},"lastModifiedTs":{"type":"integer","format":"int64","description":"Timestamp, indicating the time, when the organization was modified last time (Unix epoch milliseconds)"}},"required":["id","name","tz","lastModifiedTs"]},"Address":{"type":"object","properties":{"fullAddress":{"type":"string","maxLength":512,"description":"Full address"},"country":{"type":"string","maxLength":74,"description":"Country name"},"city":{"type":"string","maxLength":50,"description":"City name"},"state":{"type":"string","maxLength":40,"description":"State or province"},"zip":{"type":"string","maxLength":12,"description":"Postal code"}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string","description":"Error message"}},"required":["message"]}},"required":["error"]}}},"paths":{"/api/v1/organization/create":{"post":{"tags":["Organizations"],"summary":"Create a new organization","description":"Create a new organization.\n\nRequired permissions, when user-scoped authentication is used: `ORG_CREATE`.\n","operationId":"createOrganization","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string","minLength":3,"maxLength":100,"description":"Organization name. Only letters, digits, spaces, dots, hyphens, and apostrophes are allowed."},"description":{"type":"string","maxLength":1000,"description":"Organization description. Cannot contain slashes, backslashes, `<` or `>`."},"tz":{"type":"string","maxLength":200,"description":"Organization timezone in the IANA Time Zone Database (TZDB) format."},"parentId":{"type":"integer","format":"int32","description":"Parent organization ID (optional). If none is specified, the organization is created as a child of the organization associated with the authentication token."},"phoneNumber":{"type":"string","description":"Organization phone number."},"unitSystem":{"type":"string","enum":["IMPERIAL","METRIC"],"description":"Unit system used in the organization."}},"required":["name"]}}}},"responses":{"201":{"description":"Organization created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Organization"}}}},"400":{"description":"Bad request - Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden"},"429":{"description":"Too many requests"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
## Update organization name
> Update the name of an existing organization.\
> \
> Required permissions, when user-scoped authentication is used: \`ORG\_EDIT\`.
```json
{"openapi":"3.0.3","info":{"title":"Blynk Platform API","version":"1.0.0"},"tags":[{"name":"Organizations","description":"Organization management endpoints"}],"servers":[{"url":"https://{server_address}","description":"Blynk Server","variables":{"server_address":{"default":"blynk.cloud","description":"Your Blynk server domain"}}}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth2 Bearer token obtained from authentication endpoint"}},"schemas":{"Organization":{"type":"object","properties":{"id":{"type":"integer","format":"int32","description":"Organization unique identifier"},"name":{"type":"string","description":"Organization name"},"description":{"type":"string","description":"Organization description"},"parentOrganizationId":{"type":"integer","format":"int32","description":"Parent organization ID (for hierarchical structure)"},"tz":{"type":"string","description":"A timezone, associated with the organization"},"unitSystem":{"type":"string","enum":["IMPERIAL","METRIC"],"description":"Unit system used in the organization."},"phoneNumber":{"type":"string","description":"Phone number, associated with the organization."},"address":{"$ref":"#/components/schemas/Address"},"lastModifiedTs":{"type":"integer","format":"int64","description":"Timestamp, indicating the time, when the organization was modified last time (Unix epoch milliseconds)"}},"required":["id","name","tz","lastModifiedTs"]},"Address":{"type":"object","properties":{"fullAddress":{"type":"string","maxLength":512,"description":"Full address"},"country":{"type":"string","maxLength":74,"description":"Country name"},"city":{"type":"string","maxLength":50,"description":"City name"},"state":{"type":"string","maxLength":40,"description":"State or province"},"zip":{"type":"string","maxLength":12,"description":"Postal code"}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string","description":"Error message"}},"required":["message"]}},"required":["error"]}}},"paths":{"/api/v1/organization/edit/name":{"put":{"tags":["Organizations"],"summary":"Update organization name","description":"Update the name of an existing organization.\n\nRequired permissions, when user-scoped authentication is used: `ORG_EDIT`.\n","operationId":"updateOrganizationName","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orgId":{"type":"integer","format":"int32","description":"Organization ID (optional). If none is specified, the organization associated with the authentication token is being edited."},"name":{"type":"string","minLength":3,"maxLength":100,"description":"New organization name. Only letters, digits, spaces, dots, hyphens, and apostrophes are allowed."}},"required":["name"]}}}},"responses":{"200":{"description":"Organization updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Organization"}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden"},"404":{"description":"Organization not found or access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too many requests"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
## Get sub-organizations
> Retrieve a paginated list of direct sub-organizations (children) of a specified organization.\
> \
> If \`orgId\` is not specified, returns sub-organizations of the organization associated with the authentication token.\
> \
> Required permissions, when user-scoped authentication is used: \`ORG\_VIEW\`.
```json
{"openapi":"3.0.3","info":{"title":"Blynk Platform API","version":"1.0.0"},"tags":[{"name":"Organizations","description":"Organization management endpoints"}],"servers":[{"url":"https://{server_address}","description":"Blynk Server","variables":{"server_address":{"default":"blynk.cloud","description":"Your Blynk server domain"}}}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth2 Bearer token obtained from authentication endpoint"}},"schemas":{"Organization":{"type":"object","properties":{"id":{"type":"integer","format":"int32","description":"Organization unique identifier"},"name":{"type":"string","description":"Organization name"},"description":{"type":"string","description":"Organization description"},"parentOrganizationId":{"type":"integer","format":"int32","description":"Parent organization ID (for hierarchical structure)"},"tz":{"type":"string","description":"A timezone, associated with the organization"},"unitSystem":{"type":"string","enum":["IMPERIAL","METRIC"],"description":"Unit system used in the organization."},"phoneNumber":{"type":"string","description":"Phone number, associated with the organization."},"address":{"$ref":"#/components/schemas/Address"},"lastModifiedTs":{"type":"integer","format":"int64","description":"Timestamp, indicating the time, when the organization was modified last time (Unix epoch milliseconds)"}},"required":["id","name","tz","lastModifiedTs"]},"Address":{"type":"object","properties":{"fullAddress":{"type":"string","maxLength":512,"description":"Full address"},"country":{"type":"string","maxLength":74,"description":"Country name"},"city":{"type":"string","maxLength":50,"description":"City name"},"state":{"type":"string","maxLength":40,"description":"State or province"},"zip":{"type":"string","maxLength":12,"description":"Postal code"}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"object","properties":{"message":{"type":"string","description":"Error message"}},"required":["message"]}},"required":["error"]}}},"paths":{"/api/v1/organization/sub-organizations":{"get":{"tags":["Organizations"],"summary":"Get sub-organizations","description":"Retrieve a paginated list of direct sub-organizations (children) of a specified organization.\n\nIf `orgId` is not specified, returns sub-organizations of the organization associated with the authentication token.\n\nRequired permissions, when user-scoped authentication is used: `ORG_VIEW`.\n","operationId":"getSubOrganizations","parameters":[{"name":"orgId","in":"query","schema":{"type":"integer","format":"int32"},"description":"ID of the parent organization. If not specified, uses the organization from the authentication token."},{"name":"page","in":"query","schema":{"type":"integer","format":"int32","default":0,"minimum":0},"description":"Page number"},{"name":"size","in":"query","schema":{"type":"integer","format":"int32","default":50,"minimum":1,"maximum":1000},"description":"Page size (max 1000)"}],"responses":{"200":{"description":"List of sub-organizations","content":{"application/json":{"schema":{"type":"object","properties":{"content":{"type":"array","items":{"$ref":"#/components/schemas/Organization"}},"totalElements":{"type":"integer","format":"int64"}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden"},"429":{"description":"Too many requests"},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
---
# 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.blynk.io/en/blynk.cloud/platform-https-api/organizations.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.