Request Syntax URI Request Parameters Request Body Response Syntax Response Elements Errors See Also

CreateAgentSpace

Creates a new AgentSpace with the specified name and description. Duplicate space names are allowed.

Request Syntax


POST /v1/agentspaces HTTP/1.1
Content-type: application/json

{
   "clientToken": "string",
   "description": "string",
   "kmsKeyArn": "string",
   "locale": "string",
   "name": "string",
   "tags": { 
      "string" : "string" 
   }
}

URI Request Parameters

The request does not use any URI parameters.

Request Body

The request accepts the following data in JSON format.

clientToken

Client-provided token to ensure request idempotency. When the same token is provided in subsequent calls, the same response is returned within a 8-hour window.

Type: String

Length Constraints: Minimum length of 0. Maximum length of 64.

Pattern: [!-~]+

Required: No

description

The description of the AgentSpace.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 1000.

Pattern: [\p{L}\p{N}\p{P}\p{S}\p{Z}]+

Required: No

kmsKeyArn

The ARN of the AWS Key Management Service (AWS KMS) customer managed key that's used to encrypt resources.

Type: String

Length Constraints: Minimum length of 20.

Pattern: arn:aws[a-zA-Z-]*:kms:[a-z0-9-]+:[0-9]{12}:key/[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}

Required: No

locale

The locale for the AgentSpace, which determines the language used in agent responses.

Type: String

Length Constraints: Minimum length of 2. Maximum length of 35.

Pattern: [a-zA-Z]{2,3}(-[a-zA-Z0-9]{2,8})*

Required: No

name

The name of the AgentSpace.

Type: String

Length Constraints: Minimum length of 1. Maximum length of 255.

Pattern: [\p{L}\p{N}\p{P}\p{S}\p{Z}]+

Required: Yes

tags

Tags to add to the AgentSpace at creation time.

Type: String to string map

Key Length Constraints: Minimum length of 1. Maximum length of 128.

Key Pattern: [\p{L}\p{Z}\p{N}_.:/=+\-@]*

Value Length Constraints: Minimum length of 0. Maximum length of 256.

Value Pattern: [\p{L}\p{Z}\p{N}_.:/=+\-@]*

Required: No

Response Syntax


HTTP/1.1 201
Content-type: application/json

{
   "agentSpace": { 
      "agentSpaceId": "string",
      "createdAt": "string",
      "description": "string",
      "kmsKeyArn": "string",
      "locale": "string",
      "name": "string",
      "updatedAt": "string"
   },
   "tags": { 
      "string" : "string" 
   }
}

Response Elements

If the action is successful, the service sends back an HTTP 201 response.

The following data is returned in JSON format by the service.

agentSpace

Represents a complete AgentSpace with all its properties, timestamps, encryption settings, and unique identifier.

Type: AgentSpace object

tags

Tags associated with the created AgentSpace.

Type: String to string map

Key Length Constraints: Minimum length of 1. Maximum length of 128.

Key Pattern: [\p{L}\p{Z}\p{N}_.:/=+\-@]*

Value Length Constraints: Minimum length of 0. Maximum length of 256.

Value Pattern: [\p{L}\p{Z}\p{N}_.:/=+\-@]*

Errors

For information about the errors that are common to all actions, see Common Error Types.

AccessDeniedException

Access to the requested resource is denied due to insufficient permissions.

message: Detailed error message describing why access was denied.

HTTP Status Code: 403

ConflictException

The request conflicts with the current state of the resource.

message: Detailed error message describing the conflict.

HTTP Status Code: 409

ContentSizeExceededException

This exception is thrown when the content size exceeds the allowed limit.

HTTP Status Code: 413

InternalServerException

This exception is thrown when an unexpected error occurs in the processing of a request.

HTTP Status Code: 500

InvalidParameterException

One or more parameters provided in the request are invalid.

message: Detailed error message describing which parameter is invalid and why.

HTTP Status Code: 400

ResourceNotFoundException

The requested resource could not be found.

message: Detailed error message describing which resource was not found.

HTTP Status Code: 404

ServiceQuotaExceededException

The request would exceed the service quota limit.

message: Detailed error message describing which quota was exceeded.

HTTP Status Code: 402

ThrottlingException

The request was throttled due to too many requests. Please slow down and try again.

message: Detailed error message describing the throttling condition.

HTTP Status Code: 429

ValidationException

The input fails to satisfy the constraints specified by the service.

fieldList: A list of specific failures encountered while validating the input. A member can appear in this list more than once if it failed to satisfy multiple constraints.
message: A summary of the validation failure.

HTTP Status Code: 400