--- updatedAt: 2026-03-01T18:57:26.000Z agentTools: siteIndex: https://techdocs.akamai.com/llms.txt projectIndex: https://techdocs.akamai.com/edgekv/llms.txt --- # Create a namespace Creates a namespace on Akamai's `STAGING` or `PRODUCTION` network. You should create namespaces in both networks so that you can test your EdgeWorkers code on staging. # OpenAPI definition ```json { "externalDocs": { "description": "See documentation for Akamai's EdgeKV API", "url": "https://techdocs.akamai.com/edgekv/reference" }, "info": { "license": { "name": "Apache 2.0", "url": "https://www.apache.org/licenses/LICENSE-2.0.html" }, "title": "Namespaces and data", "version": "v1" }, "openapi": "3.0.0", "paths": { "/networks/{network}/namespaces": { "post": { "description": "Creates a namespace on Akamai's `STAGING` or `PRODUCTION` network. You should create namespaces in both networks so that you can test your EdgeWorkers code on staging.", "externalDocs": { "description": "See documentation for this operation in Akamai's EdgeKV API", "url": "https://techdocs.akamai.com/edgekv/reference/post-namespace" }, "operationId": "post-namespace", "parameters": [ { "description": "For customers who manage more than one account, this [runs the operation from another account](https://techdocs.akamai.com/developer/docs/manage-many-accounts-with-one-api-client). The Identity and Access Management API provides a [list of available account switch keys](https://techdocs.akamai.com/iam-api/reference/get-client-account-switch-keys).", "in": "query", "name": "accountSwitchKey", "required": false, "schema": { "example": "1-5C0YLB:1-8BYUX", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "geoLocation": "US", "groupId": 12345, "namespace": "marketing", "retentionInSeconds": 15724800 }, "schema": { "additionalProperties": false, "description": "Represents an EdgeKV namespace.", "properties": { "dataAccessPolicy": { "additionalProperties": false, "description": "Overrides the default data access policy. If not specified, all new namespaces use the current `dataAccessPolicy`. The default data access policy is defined when first initializing EdgeKV. You can change the settings for new namespaces by running the [Modify the default data access policy](https://techdocs.akamai.com/edgekv/reference/put-auth-database) operation after initialization. You can't change the data access policy after you create a namespace.", "properties": { "policyType": { "default": "inherited", "description": "__Read-only__ Indicates if the default data access policy has been `inherited` or `overridden`.", "enum": [ "inherited", "overridden" ], "readOnly": true, "type": "string" }, "restrictDataAccess": { "description": "Set a data access policy to override the default setting. You can only change the data access policy for a namespace if `allowNamespacePolicyOverride` is set to `true` when first initializing EdgeKV. You can also use the [Modify the default data access policy](https://techdocs.akamai.com/edgekv/reference/put-auth-database) endpoint to change the settings after initialization is complete.", "type": "boolean" } }, "required": [ "restrictDataAccess", "policyType" ], "type": "object" }, "geoLocation": { "default": "US", "description": "__Write-once__ Specifies the storage location for data when creating a namespace on the production network. This can help optimize performance by storing data where most of your users are located. Once you set this value, you can't modify it. The value defaults to `US` on the `STAGING` and `PRODUCTION` networks. The available locations on the `PRODUCTION` network also include `EU` (Europe), `JP` (Japan), and `GLOBAL`. The `GLOBAL` location automatically replicates data to `US`, `EU`, and `JP` storage locations. If you use the `GLOBAL` location, reads are faster but write operations are slightly slower.", "enum": [ "US", "EU", "JP", "GLOBAL" ], "type": "string", "x-akamai": { "write-once": true } }, "groupId": { "description": "The Akamai access group the namespace is assigned to. A value of `0` makes the namespace available to all Akamai access groups on the account with EdgeKV capabilities.", "minimum": 0, "type": "integer" }, "namespace": { "description": "A name for a namespace.", "type": "string" }, "namespaceStatus": { "description": "__Read-only__ Specifies the current status of the namespace. A status of `READY` indicates that all reads and writes are enabled.\nA status of `DELETING` indicates that the namespace is scheduled for deletion\nand all reads and writes are disabled.", "enum": [ "READY", "DELETING" ], "readOnly": true, "type": "string" }, "retentionInSeconds": { "description": "Retention period of underlying data, represented in seconds. Accepts values between `86400` for one day and `315360000` for 10 years. You can also enter a value of `0` to retain data indefinitely.", "oneOf": [ { "enum": [ 0 ], "title": "Retain data indefinitely" }, { "maximum": 315360000, "minimum": 86400, "title": "Retain data for a specific period" } ], "type": "integer" }, "scheduledDeleteTime": { "description": "__Read-only__ Specifies the time scheduled time for a namespace delete, in ISO 8601 format. A value only appears when a scheduled delete is pending for the namespace.", "format": "date-time", "readOnly": true, "type": "string" } }, "required": [ "namespace", "retentionInSeconds", "groupId" ], "type": "object", "x-akamai": { "file-path": "schemas/namespace.yaml" } } } } }, "responses": { "200": { "content": { "application/json": { "example": { "geoLocation": "US", "groupId": 32145, "namespace": "marketing", "retentionInSeconds": 15724800 }, "schema": { "additionalProperties": false, "description": "Represents an EdgeKV namespace.", "properties": { "dataAccessPolicy": { "additionalProperties": false, "description": "Overrides the default data access policy. If not specified, all new namespaces use the current `dataAccessPolicy`. The default data access policy is defined when first initializing EdgeKV. You can change the settings for new namespaces by running the [Modify the default data access policy](https://techdocs.akamai.com/edgekv/reference/put-auth-database) operation after initialization. You can't change the data access policy after you create a namespace.", "properties": { "policyType": { "default": "inherited", "description": "__Read-only__ Indicates if the default data access policy has been `inherited` or `overridden`.", "enum": [ "inherited", "overridden" ], "readOnly": true, "type": "string" }, "restrictDataAccess": { "description": "Set a data access policy to override the default setting. You can only change the data access policy for a namespace if `allowNamespacePolicyOverride` is set to `true` when first initializing EdgeKV. You can also use the [Modify the default data access policy](https://techdocs.akamai.com/edgekv/reference/put-auth-database) endpoint to change the settings after initialization is complete.", "type": "boolean" } }, "required": [ "restrictDataAccess", "policyType" ], "type": "object" }, "geoLocation": { "default": "US", "description": "__Write-once__ Specifies the storage location for data when creating a namespace on the production network. This can help optimize performance by storing data where most of your users are located. Once you set this value, you can't modify it. The value defaults to `US` on the `STAGING` and `PRODUCTION` networks. The available locations on the `PRODUCTION` network also include `EU` (Europe), `JP` (Japan), and `GLOBAL`. The `GLOBAL` location automatically replicates data to `US`, `EU`, and `JP` storage locations. If you use the `GLOBAL` location, reads are faster but write operations are slightly slower.", "enum": [ "US", "EU", "JP", "GLOBAL" ], "type": "string", "x-akamai": { "write-once": true } }, "groupId": { "description": "The Akamai access group the namespace is assigned to. A value of `0` makes the namespace available to all Akamai access groups on the account with EdgeKV capabilities.", "minimum": 0, "type": "integer" }, "namespace": { "description": "A name for a namespace.", "type": "string" }, "namespaceStatus": { "description": "__Read-only__ Specifies the current status of the namespace. A status of `READY` indicates that all reads and writes are enabled.\nA status of `DELETING` indicates that the namespace is scheduled for deletion\nand all reads and writes are disabled.", "enum": [ "READY", "DELETING" ], "readOnly": true, "type": "string" }, "retentionInSeconds": { "description": "Retention period of underlying data, represented in seconds. Accepts values between `86400` for one day and `315360000` for 10 years. You can also enter a value of `0` to retain data indefinitely.", "oneOf": [ { "enum": [ 0 ], "title": "Retain data indefinitely" }, { "maximum": 315360000, "minimum": 86400, "title": "Retain data for a specific period" } ], "type": "integer" }, "scheduledDeleteTime": { "description": "__Read-only__ Specifies the time scheduled time for a namespace delete, in ISO 8601 format. A value only appears when a scheduled delete is pending for the namespace.", "format": "date-time", "readOnly": true, "type": "string" } }, "required": [ "namespace", "retentionInSeconds", "groupId" ], "type": "object", "x-akamai": { "file-path": "schemas/namespace.yaml" } } } }, "description": "Successful response." }, "400": { "content": { "application/problem+json": { "examples": { "cannot-change-groupid": { "summary": "Can't change groupId", "value": { "additionalDetail": { "requestId": "5d424b9289ab9b43" }, "detail": "groupId changes must be made through the reauthorize endpoint.", "errorCode": "EKV_3000", "instance": "/edgekv/error-instances/2c82be29-f909-4d42-b775-de404e264fd9", "status": 400, "title": "Bad Request", "type": "/edgekv/error-types/edgekv-bad-request" } }, "invalid-namespace": { "summary": "Invalid Namespace", "value": { "additionalDetail": { "requestId": "baaf61e18fa20d95" }, "detail": "Retention period must be specified.", "errorCode": "EKV_2000", "instance": "/edgekv/error-instances/48361e23-541d-4c39-ab4b-c8a194889b27", "status": 400, "title": "Bad Request", "type": "/edgekv/error-types/edgekv-bad-request" } } }, "schema": { "additionalProperties": true, "description": "Error messaging.", "properties": { "additionalDetail": { "additionalProperties": false, "description": "More details about the error.", "properties": { "requestId": { "description": "Request identifier.", "type": "string" } }, "type": "object" }, "detail": { "description": "A description of the error.", "type": "string" }, "errorCode": { "description": "Internal error code used to assist with troubleshooting by Akamai employees.", "type": "string" }, "instance": { "description": "Reference to unique instance of the error.", "type": "string" }, "status": { "description": "The HTTP code for the error.", "type": "integer" }, "title": { "description": "Text representation of the HTTP error code.", "type": "string" }, "type": { "description": "Reference to additional documentation.", "type": "string" } }, "type": "object", "x-akamai": { "file-path": "schemas/error.yaml" } } } }, "description": "[Bad request](https://techdocs.akamai.com/edgekv/reference/400). Invalid namespace name or missing attribute.", "x-akamai": { "file-path": "errors/400-namespace-invalid.yaml" } }, "409": { "content": { "application/problem+json": { "example": { "additionalDetail": { "requestId": "c04b61e191f202f3" }, "detail": "A namespace with the name marketing already exists with a different configuration", "errorCode": "EKV_3000", "instance": "/edgekv/error-instances/990ac1c3-aa20-4cb8-91fd-9c791d7653f5", "status": 409, "title": "Conflict", "type": "/edgekv/error-types/edgekv-conflict" }, "schema": { "additionalProperties": true, "description": "Error messaging.", "properties": { "additionalDetail": { "additionalProperties": false, "description": "More details about the error.", "properties": { "requestId": { "description": "Request identifier.", "type": "string" } }, "type": "object" }, "detail": { "description": "A description of the error.", "type": "string" }, "errorCode": { "description": "Internal error code used to assist with troubleshooting by Akamai employees.", "type": "string" }, "instance": { "description": "Reference to unique instance of the error.", "type": "string" }, "status": { "description": "The HTTP code for the error.", "type": "integer" }, "title": { "description": "Text representation of the HTTP error code.", "type": "string" }, "type": { "description": "Reference to additional documentation.", "type": "string" } }, "type": "object", "x-akamai": { "file-path": "schemas/error.yaml" } } } }, "description": "[Conflict](https://techdocs.akamai.com/edgekv/reference/409). Namespace name already exists.", "x-akamai": { "file-path": "errors/409-namespace.yaml" } }, "500": { "content": { "application/problem+json": { "example": { "additionalDetail": { "requestId": "cd9b61e08148009b" }, "detail": "An internal error occurred.", "errorCode": "EKV_0000", "instance": "/edgekv/error-instances/cdb7767c-817e-4805-9f28-0816eefa0ba8", "status": 500, "title": "Internal Server Error", "type": "/edgekv/error-types/edgekv-internal-server-error" }, "schema": { "additionalProperties": true, "description": "Error messaging.", "properties": { "additionalDetail": { "additionalProperties": false, "description": "More details about the error.", "properties": { "requestId": { "description": "Request identifier.", "type": "string" } }, "type": "object" }, "detail": { "description": "A description of the error.", "type": "string" }, "errorCode": { "description": "Internal error code used to assist with troubleshooting by Akamai employees.", "type": "string" }, "instance": { "description": "Reference to unique instance of the error.", "type": "string" }, "status": { "description": "The HTTP code for the error.", "type": "integer" }, "title": { "description": "Text representation of the HTTP error code.", "type": "string" }, "type": { "description": "Reference to additional documentation.", "type": "string" } }, "type": "object", "x-akamai": { "file-path": "schemas/error.yaml" } } } }, "description": "[Internal server error](https://techdocs.akamai.com/edgekv/reference/500).", "x-akamai": { "file-path": "errors/500.yaml" } } }, "summary": "Create a namespace", "tags": [ "Namespaces" ] }, "parameters": [ { "description": "__Enum__ Network environment to execute the API request on.", "in": "path", "name": "network", "required": true, "schema": { "enum": [ "production", "staging" ], "example": "staging", "type": "string" }, "x-akamai": { "file-path": "parameters/network-path.yaml" } } ], "x-akamai": { "file-path": "paths/namespaces.yaml", "path-info": "/networks/{network}/namespaces" } } }, "servers": [ { "url": "https://{hostname}/edgekv/v1" } ], "x-akamai": { "auth-type": "EDGE_GRID", "file-path": "04-networks.yaml" }, "x-readme": { "samples-languages": [ "curl", "python", "node" ] } } ``` # Sibling pages * [List namespaces](https://techdocs.akamai.com/edgekv/reference/get-namespaces.md) * [Get namespace details](https://techdocs.akamai.com/edgekv/reference/get-namespace.md) * [Update namespace details](https://techdocs.akamai.com/edgekv/reference/put-namespace.md) * [Delete namespace](https://techdocs.akamai.com/edgekv/reference/delete-namespace.md) * [List groups within a namespace](https://techdocs.akamai.com/edgekv/reference/get-namespace-groups.md) * [Download namespace data](https://techdocs.akamai.com/edgekv/reference/get-namespace-download.md) * [Get namespace delete time](https://techdocs.akamai.com/edgekv/reference/get-scheduled-delete.md) * [Reschedule a namespace delete](https://techdocs.akamai.com/edgekv/reference/put-scheduled-delete.md) * [Download group data](https://techdocs.akamai.com/edgekv/reference/get-group-download.md) * [Cancel a scheduled namespace delete](https://techdocs.akamai.com/edgekv/reference/delete-scheduled-delete.md) * [Get namespace upload job details](https://techdocs.akamai.com/edgekv/reference/get-namespace-upload-job.md) * [Upload namespace data](https://techdocs.akamai.com/edgekv/reference/post-namespace-upload.md) * [List upload jobs](https://techdocs.akamai.com/edgekv/reference/get-namespace-upload.md)