> For the complete documentation index, see [llms.txt](https://developer.gospace.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.gospace.com/partners/partner-api.md).

# Partner API

## GET /organisations

> List child organisations owned by the authenticated partner. Deleted organisations are excluded by default.

```json
{"openapi":"3.0.3","info":{"title":"Partner API","version":"1.0"},"servers":[{"url":"https://api.gospace.app/partner/v1"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"PartnerOrganisation":{"type":"object","properties":{"organisation_id":{"type":"string","description":"MongoDB identifier for the organisation."},"organisation_key":{"type":"string","description":"gospace organisation key used for tenant context."},"organisation_name":{"type":"string"},"country":{"type":"string","minLength":2,"maxLength":2},"division_key":{"type":"string","description":"Initial division key created with the organisation."},"deleted_at":{"type":"string","format":"date-time","nullable":true},"partner_external_id":{"type":"string","description":"Optional partner-side identifier for this organisation."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["organisation_id","organisation_key","organisation_name","country","created_at","updated_at"]},"ErrorEnvelope":{"type":"object","properties":{"success":{"type":"boolean"},"identifier":{"type":"string"},"error":{"type":"object","additionalProperties":true},"violation":{"type":"object","additionalProperties":true}},"required":["success","identifier"]}},"responses":{"Unauthorised":{"description":"Missing, malformed, disabled, deleted, or non-partner API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"InternalServerError":{"description":"Internal Server Error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"paths":{"/organisations":{"get":{"operationId":"listPartnerOrganisations","description":"List child organisations owned by the authenticated partner. Deleted organisations are excluded by default.","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":50}},{"name":"skip","in":"query","required":false,"schema":{"type":"integer","minimum":0,"default":0}},{"name":"include_deleted","in":"query","required":false,"schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Organisations listed.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"identifier":{"type":"string","enum":["partner_organisations_listed"]},"data":{"type":"array","items":{"$ref":"#/components/schemas/PartnerOrganisation"}}},"required":["success","identifier","data"]}}}},"401":{"$ref":"#/components/responses/Unauthorised"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## POST /organisations

> Create a child organisation owned by the authenticated partner. The response includes one newly generated standard organisation API key. Use that child organisation API key for data writes into the child organisation.

```json
{"openapi":"3.0.3","info":{"title":"Partner API","version":"1.0"},"servers":[{"url":"https://api.gospace.app/partner/v1"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"CreatePartnerOrganisationRequest":{"type":"object","properties":{"organisation_name":{"type":"string","minLength":1},"country":{"type":"string","minLength":2,"maxLength":2,"description":"ISO 3166-1 alpha-2 country code."},"division_timezone":{"type":"string","minLength":1},"division_name":{"type":"string","minLength":1,"description":"Optional name for the initial division. Defaults to `organisation_name`."},"partner_external_id":{"type":"string","minLength":1,"description":"Optional partner-side identifier for this organisation."}},"required":["organisation_name","country","division_timezone"]},"PartnerOrganisationWithApiKey":{"allOf":[{"$ref":"#/components/schemas/PartnerOrganisation"},{"type":"object","properties":{"organisation_api_key":{"type":"string","description":"Newly generated standard organisation API key. Returned only when the organisation is created."}},"required":["organisation_api_key"]}]},"PartnerOrganisation":{"type":"object","properties":{"organisation_id":{"type":"string","description":"MongoDB identifier for the organisation."},"organisation_key":{"type":"string","description":"gospace organisation key used for tenant context."},"organisation_name":{"type":"string"},"country":{"type":"string","minLength":2,"maxLength":2},"division_key":{"type":"string","description":"Initial division key created with the organisation."},"deleted_at":{"type":"string","format":"date-time","nullable":true},"partner_external_id":{"type":"string","description":"Optional partner-side identifier for this organisation."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["organisation_id","organisation_key","organisation_name","country","created_at","updated_at"]},"ErrorEnvelope":{"type":"object","properties":{"success":{"type":"boolean"},"identifier":{"type":"string"},"error":{"type":"object","additionalProperties":true},"violation":{"type":"object","additionalProperties":true}},"required":["success","identifier"]}},"responses":{"Unauthorised":{"description":"Missing, malformed, disabled, deleted, or non-partner API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"InternalServerError":{"description":"Internal Server Error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"paths":{"/organisations":{"post":{"operationId":"createPartnerOrganisation","description":"Create a child organisation owned by the authenticated partner. The response includes one newly generated standard organisation API key. Use that child organisation API key for data writes into the child organisation.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePartnerOrganisationRequest"}}}},"responses":{"200":{"description":"Organisation created.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"identifier":{"type":"string","enum":["partner_organisation_created"]},"data":{"$ref":"#/components/schemas/PartnerOrganisationWithApiKey"}},"required":["success","identifier","data"]}}}},"400":{"description":"Bad Request - Invalid request body."},"401":{"$ref":"#/components/responses/Unauthorised"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## GET /organisations/{organisation\_id}

> Retrieve one child organisation by MongoDB organisation ID. Organisations not owned by the authenticated partner are rejected.

```json
{"openapi":"3.0.3","info":{"title":"Partner API","version":"1.0"},"servers":[{"url":"https://api.gospace.app/partner/v1"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"PartnerOrganisation":{"type":"object","properties":{"organisation_id":{"type":"string","description":"MongoDB identifier for the organisation."},"organisation_key":{"type":"string","description":"gospace organisation key used for tenant context."},"organisation_name":{"type":"string"},"country":{"type":"string","minLength":2,"maxLength":2},"division_key":{"type":"string","description":"Initial division key created with the organisation."},"deleted_at":{"type":"string","format":"date-time","nullable":true},"partner_external_id":{"type":"string","description":"Optional partner-side identifier for this organisation."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["organisation_id","organisation_key","organisation_name","country","created_at","updated_at"]},"ErrorEnvelope":{"type":"object","properties":{"success":{"type":"boolean"},"identifier":{"type":"string"},"error":{"type":"object","additionalProperties":true},"violation":{"type":"object","additionalProperties":true}},"required":["success","identifier"]}},"responses":{"Unauthorised":{"description":"Missing, malformed, disabled, deleted, or non-partner API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"PartnerOrganisationNotFound":{"description":"Organisation not found or not owned by the authenticated partner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"InternalServerError":{"description":"Internal Server Error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"paths":{"/organisations/{organisation_id}":{"get":{"operationId":"getPartnerOrganisation","description":"Retrieve one child organisation by MongoDB organisation ID. Organisations not owned by the authenticated partner are rejected.","parameters":[{"name":"organisation_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f\\\\d]{24}$"}},{"name":"include_deleted","in":"query","required":false,"schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Organisation found.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"identifier":{"type":"string","enum":["partner_organisation_found"]},"data":{"$ref":"#/components/schemas/PartnerOrganisation"}},"required":["success","identifier","data"]}}}},"401":{"$ref":"#/components/responses/Unauthorised"},"404":{"$ref":"#/components/responses/PartnerOrganisationNotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## DELETE /organisations/{organisation\_id}

> Soft-delete an owned child organisation and revoke its organisation API keys. If the deleted target is itself a partner organisation, child organisations linked to that partner are also soft-deleted and their keys revoked.

```json
{"openapi":"3.0.3","info":{"title":"Partner API","version":"1.0"},"servers":[{"url":"https://api.gospace.app/partner/v1"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"DeletePartnerOrganisationResult":{"type":"object","properties":{"organisation_ids":{"type":"array","description":"Organisation IDs that were soft-deleted.","items":{"type":"string"}}},"required":["organisation_ids"]},"ErrorEnvelope":{"type":"object","properties":{"success":{"type":"boolean"},"identifier":{"type":"string"},"error":{"type":"object","additionalProperties":true},"violation":{"type":"object","additionalProperties":true}},"required":["success","identifier"]}},"responses":{"Unauthorised":{"description":"Missing, malformed, disabled, deleted, or non-partner API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"PartnerOrganisationNotFound":{"description":"Organisation not found or not owned by the authenticated partner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"InternalServerError":{"description":"Internal Server Error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"paths":{"/organisations/{organisation_id}":{"delete":{"operationId":"deletePartnerOrganisation","description":"Soft-delete an owned child organisation and revoke its organisation API keys. If the deleted target is itself a partner organisation, child organisations linked to that partner are also soft-deleted and their keys revoked.","parameters":[{"name":"organisation_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f\\\\d]{24}$"}}],"responses":{"200":{"description":"Organisation deleted.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"identifier":{"type":"string","enum":["partner_organisation_deleted"]},"data":{"$ref":"#/components/schemas/DeletePartnerOrganisationResult"}},"required":["success","identifier","data"]}}}},"401":{"$ref":"#/components/responses/Unauthorised"},"404":{"$ref":"#/components/responses/PartnerOrganisationNotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## PATCH /organisations/{organisation\_id}

> Update safe partner-facing organisation metadata only. Fields such as \`country\`, \`location\`, \`shard\_key\`, \`organisation\_key\`, \`divisions\`, \`is\_partner\`, and ownership fields cannot be updated through this API.

```json
{"openapi":"3.0.3","info":{"title":"Partner API","version":"1.0"},"servers":[{"url":"https://api.gospace.app/partner/v1"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"UpdatePartnerOrganisationRequest":{"type":"object","additionalProperties":false,"properties":{"organisation_name":{"type":"string","minLength":1},"partner_external_id":{"type":"string","minLength":1}},"minProperties":1},"PartnerOrganisation":{"type":"object","properties":{"organisation_id":{"type":"string","description":"MongoDB identifier for the organisation."},"organisation_key":{"type":"string","description":"gospace organisation key used for tenant context."},"organisation_name":{"type":"string"},"country":{"type":"string","minLength":2,"maxLength":2},"division_key":{"type":"string","description":"Initial division key created with the organisation."},"deleted_at":{"type":"string","format":"date-time","nullable":true},"partner_external_id":{"type":"string","description":"Optional partner-side identifier for this organisation."},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}},"required":["organisation_id","organisation_key","organisation_name","country","created_at","updated_at"]},"ErrorEnvelope":{"type":"object","properties":{"success":{"type":"boolean"},"identifier":{"type":"string"},"error":{"type":"object","additionalProperties":true},"violation":{"type":"object","additionalProperties":true}},"required":["success","identifier"]}},"responses":{"Unauthorised":{"description":"Missing, malformed, disabled, deleted, or non-partner API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"PartnerOrganisationNotFound":{"description":"Organisation not found or not owned by the authenticated partner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"InternalServerError":{"description":"Internal Server Error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"paths":{"/organisations/{organisation_id}":{"patch":{"operationId":"updatePartnerOrganisation","description":"Update safe partner-facing organisation metadata only. Fields such as `country`, `location`, `shard_key`, `organisation_key`, `divisions`, `is_partner`, and ownership fields cannot be updated through this API.","parameters":[{"name":"organisation_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f\\\\d]{24}$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdatePartnerOrganisationRequest"}}}},"responses":{"200":{"description":"Organisation updated.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"identifier":{"type":"string","enum":["partner_organisation_updated"]},"data":{"$ref":"#/components/schemas/PartnerOrganisation"}},"required":["success","identifier","data"]}}}},"400":{"description":"Bad Request - Invalid request body."},"401":{"$ref":"#/components/responses/Unauthorised"},"404":{"$ref":"#/components/responses/PartnerOrganisationNotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```

## GET /organisations/{organisation\_id}/usage

> Retrieve storage and API request usage for an owned child organisation for a single month. Monthly totals are returned when available; otherwise daily storage and API usage records are aggregated.

```json
{"openapi":"3.0.3","info":{"title":"Partner API","version":"1.0"},"servers":[{"url":"https://api.gospace.app/partner/v1"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key"}},"schemas":{"PartnerUsage":{"type":"object","properties":{"organisation_id":{"type":"string"},"organisation_key":{"type":"string"},"usage_month":{"type":"string","pattern":"^\\\\d{4}-\\\\d{2}$"},"timezone":{"type":"string"},"total_bytes":{"type":"number","default":0},"total_documents":{"type":"number","default":0},"days_recorded":{"type":"number","default":0},"peak_total_bytes":{"type":"number","default":0},"peak_total_documents":{"type":"number","default":0},"total_requests":{"type":"number","default":0},"api_days_recorded":{"type":"number","default":0},"peak_total_requests":{"type":"number","default":0}},"required":["organisation_id","organisation_key","usage_month","timezone","total_bytes","total_documents","days_recorded","peak_total_bytes","peak_total_documents","total_requests","api_days_recorded","peak_total_requests"]},"ErrorEnvelope":{"type":"object","properties":{"success":{"type":"boolean"},"identifier":{"type":"string"},"error":{"type":"object","additionalProperties":true},"violation":{"type":"object","additionalProperties":true}},"required":["success","identifier"]}},"responses":{"Unauthorised":{"description":"Missing, malformed, disabled, deleted, or non-partner API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"PartnerOrganisationNotFound":{"description":"Organisation not found or not owned by the authenticated partner.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"InternalServerError":{"description":"Internal Server Error.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}},"paths":{"/organisations/{organisation_id}/usage":{"get":{"operationId":"getPartnerOrganisationUsage","description":"Retrieve storage and API request usage for an owned child organisation for a single month. Monthly totals are returned when available; otherwise daily storage and API usage records are aggregated.","parameters":[{"name":"organisation_id","in":"path","required":true,"schema":{"type":"string","pattern":"^[a-f\\\\d]{24}$"}},{"name":"usage_month","in":"query","required":true,"schema":{"type":"string","pattern":"^\\\\d{4}-\\\\d{2}$"}}],"responses":{"200":{"description":"Usage found.","content":{"application/json":{"schema":{"type":"object","properties":{"success":{"type":"boolean"},"identifier":{"type":"string","enum":["partner_organisation_usage_found"]},"data":{"$ref":"#/components/schemas/PartnerUsage"}},"required":["success","identifier","data"]}}}},"400":{"description":"Bad Request - Invalid usage month."},"401":{"$ref":"#/components/responses/Unauthorised"},"404":{"$ref":"#/components/responses/PartnerOrganisationNotFound"},"500":{"$ref":"#/components/responses/InternalServerError"}}}}}}
```