{"type":"api","title":"Bulk transfer agents","meta":{"id":"/apps/pubhub/media/000-v7-apis/5b3454a4300b838cc17f7b2cdc0690fdd15058d5/8ebf57c6-5c11-32a6-b382-0c79fa6e8efc","info":{"description":"Manage ThousandEyes Endpoint Agents using this API. \n\nFor more information about Endpoint Agents, see [Endpoint Agents](https://docs.thousandeyes.com/product-documentation/global-vantage-points/endpoint-agents).","title":"Endpoint Agents API","version":"7.0.34"},"security":[{"BearerAuth":[]}],"tags":[{"name":"Endpoint Agents"},{"name":"Endpoint Agents Transfer"}],"openapi":"3.0.1","servers":[{"description":"ThousandEyes API production URL","url":"https://api.thousandeyes.com/v7"}],"securitySchemes":{"BearerAuth":{"description":"Bearer authentication token","scheme":"bearer","type":"http"}}},"spec":{"description":"Initiates the transfer of multiple agents between accounts. The following conditions apply:\n\n* The requester must possess 'write' permissions for both the 'from' and 'to' accounts involved in each transfer.\n\n* Multiple transfers may involve a mix of different source and destination accounts.\n* For each transfer request, the 'from' account must match the current account of the respective agent.\n* Transfers are executed asynchronously.\n* Progress tracking is not intended, but users can monitor the progress by periodically polling the 'get agent' endpoint.\n* Each transfer request is individually validated and completed; this operation is not atomic, meaning transfers can succeed or fail individually.\n* The API response provides the status of each transfer request.\n","operationId":"transferEndpointAgents","parameters":[{"description":"A unique identifier associated with your account group. You can retrieve your `AccountGroupId` from the `/account-groups` endpoint. Note that you must be assigned to the target account group. Specifying this parameter without being assigned to the target account group will result in an error response.","in":"query","name":"aid","required":false,"schema":{"example":"1234","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"properties":{"transfers":{"items":{"properties":{"agentId":{"description":"Unique ID of endpoint agent, from `/endpoint/agents` endpoint.","example":"861b7557-cd57-4bbb-b648-00bddf88ef49","format":"uuid","readOnly":true,"type":"string","$$ref":"#/components/schemas/EndpointAgentId"},"fromAid":{"description":"A unique identifier associated with your account group. You can retrieve your `AccountGroupId` from the `/account-groups` endpoint.","example":"1234","type":"string","$$ref":"#/components/schemas/AccountId"},"toAid":{"description":"A unique identifier associated with your account group. You can retrieve your `AccountGroupId` from the `/account-groups` endpoint.","example":"1234","type":"string","$$ref":"#/components/schemas/AccountId"}},"type":"object","example":{"agentId":"5d0764ac-7e42-4ec8-a0d4-39fc53edccba","fromAid":"1234","toAid":"12345"},"$$ref":"#/components/schemas/AgentTransfer"},"type":"array"}},"type":"object","$$ref":"#/components/schemas/BulkAgentTransferRequest"}},"text/csv":{"examples":{"CSV File":{"value":"agent_id,from_aid,to_aid\n5d0764ac-7e42-4ec8-a0d4-39fc53edccba,111,222\n1234abcd-7e42-4ec8-a0d4-39fc53abcdef,222,333\n","$$ref":"#/components/examples/TransferCSV"}},"schema":{"type":"string"}},"text/plain":{"examples":{"CSV File":{"value":"agent_id,from_aid,to_aid\n5d0764ac-7e42-4ec8-a0d4-39fc53edccba,111,222\n1234abcd-7e42-4ec8-a0d4-39fc53abcdef,222,333\n","$$ref":"#/components/examples/TransferCSV"}},"schema":{"type":"string"}}},"description":"A collection of `AgentTransfers`.","$$ref":"#/components/requestBodies/AgentTransfers"},"responses":{"207":{"content":{"application/hal+json":{"schema":{"properties":{"items":{"example":[{"status":200,"detail":"Initiated","request":{"agentId":"5d0764ac-7e42-4ec8-a0d4-39fc53edccba","fromAid":"1234","toAid":"12345"}},{"status":400,"detail":"Missing from-account id","request":{"agentId":"5d0764ac-7e42-4ec8-a0d5-39fc53ed1234","fromAid":"xxx","toAid":"12345"}},{"status":403,"detail":"User does not have permission on 'to' aid","request":{"agentId":"5d0764ac-7e42-4ec8-a0d5-39fc53ed7890","fromAid":"1234","toAid":"12345"}}],"items":{"properties":{"type":{"description":"A URI reference that identifies the problem type. When this member is not present, its value is assumed to be \"about:blank\".","type":"string"},"title":{"description":"A short, human-readable summary of the problem type.","type":"string"},"status":{"description":"The HTTP status code generated by the origin server for this occurrence of the problem.","type":"integer"},"detail":{"description":"A human-readable explanation specific to this occurrence of the problem.","type":"string"},"instance":{"description":"A URI reference that identifies the specific occurrence of the problem.","type":"string"},"request":{"properties":{"agentId":{"description":"Unique ID of endpoint agent, from `/endpoint/agents` endpoint.","example":"861b7557-cd57-4bbb-b648-00bddf88ef49","format":"uuid","readOnly":true,"type":"string","$$ref":"#/components/schemas/EndpointAgentId"},"fromAid":{"description":"A unique identifier associated with your account group. You can retrieve your `AccountGroupId` from the `/account-groups` endpoint.","example":"1234","type":"string","$$ref":"#/components/schemas/AccountId"},"toAid":{"description":"A unique identifier associated with your account group. You can retrieve your `AccountGroupId` from the `/account-groups` endpoint.","example":"1234","type":"string","$$ref":"#/components/schemas/AccountId"}},"type":"object","example":{"agentId":"5d0764ac-7e42-4ec8-a0d4-39fc53edccba","fromAid":"1234","toAid":"12345"},"$$ref":"#/components/schemas/AgentTransfer"}},"type":"object","$$ref":"#/components/schemas/AgentTransferStatus"},"type":"array"}},"type":"object","$$ref":"#/components/schemas/BulkAgentTransferResponse"}}},"description":"Transfer initiated"},"400":{"content":{"application/problem+json":{"example":{"type":"about:blank","title":"Request validation failed. There are invalid or missing fields","status":400,"detail":"Your request object contains invalid fields.","instance":"/v7","errors":[{"code":"AM-5432","field":"firstName","message":"firstName cannot have fancy characters"},{"code":"DASH-5622","field":"password","message":"Password cannot be blank"}]},"schema":{"properties":{"type":{"description":"A URI reference that identifies the problem type. When this member is not present, its value is assumed to be \"about:blank\".","type":"string"},"title":{"description":"A short, human-readable summary of the problem type.","type":"string"},"status":{"description":"The HTTP status code generated by the origin server for this occurrence of the problem.","type":"integer"},"detail":{"description":"A human-readable explanation specific to this occurrence of the problem.","type":"string"},"instance":{"description":"A URI reference that identifies the specific occurrence of the problem.","type":"string"},"errors":{"description":"(Optional) When multiple errors occur, the details for each error are listed.","items":{"properties":{"code":{"description":"(Optional) A unique error type/code that can be referenced in the documentation for further details.","type":"string"},"field":{"description":"Identifies the field that triggered this particular error.","type":"string"},"message":{"description":"A short, human-readable summary of the error.","type":"string"}},"type":"object","$$ref":"#/components/schemas/ValidationErrorItem"},"nullable":true,"type":"array"}},"type":"object","$$ref":"#/components/schemas/ValidationError"}}},"description":"Bad Request"},"401":{"content":{"application/problem+json":{"schema":{"properties":{"error":{"example":"invalid_token","type":"string"},"error_description":{"example":"Invalid access token","type":"string"}},"type":"object","$$ref":"#/components/schemas/UnauthorizedError"}}},"description":"Unauthorized"},"403":{"content":{"application/problem+json":{"schema":{"properties":{"type":{"description":"A URI reference that identifies the problem type. When this member is not present, its value is assumed to be \"about:blank\".","type":"string"},"title":{"description":"A short, human-readable summary of the problem type.","type":"string"},"status":{"description":"The HTTP status code generated by the origin server for this occurrence of the problem.","type":"integer"},"detail":{"description":"A human-readable explanation specific to this occurrence of the problem.","type":"string"},"instance":{"description":"A URI reference that identifies the specific occurrence of the problem.","type":"string"}},"type":"object","$$ref":"#/components/schemas/Error"}}},"description":"Insufficient permissions to query endpoint"},"404":{"content":{"application/problem+json":{"example":{"type":"about:blank","title":"URI Resource Not Found","status":404,"detail":"Details explaining if the 404 error is related to an invalid URI or a wrong ID","instance":"/v7"},"schema":{"properties":{"type":{"description":"A URI reference that identifies the problem type. When this member is not present, its value is assumed to be \"about:blank\".","type":"string"},"title":{"description":"A short, human-readable summary of the problem type.","type":"string"},"status":{"description":"The HTTP status code generated by the origin server for this occurrence of the problem.","type":"integer"},"detail":{"description":"A human-readable explanation specific to this occurrence of the problem.","type":"string"},"instance":{"description":"A URI reference that identifies the specific occurrence of the problem.","type":"string"}},"type":"object","$$ref":"#/components/schemas/Error"}}},"description":"Not found"},"429":{"content":{"application/problem+json":{"schema":{"properties":{"type":{"description":"A URI reference that identifies the problem type. When this member is not present, its value is assumed to be \"about:blank\".","type":"string"},"title":{"description":"A short, human-readable summary of the problem type.","type":"string"},"status":{"description":"The HTTP status code generated by the origin server for this occurrence of the problem.","type":"integer"},"detail":{"description":"A human-readable explanation specific to this occurrence of the problem.","type":"string"},"instance":{"description":"A URI reference that identifies the specific occurrence of the problem.","type":"string"}},"type":"object","$$ref":"#/components/schemas/Error"}}},"description":"Exhausted rate limit for the organization"}},"summary":"Bulk transfer agents","tags":["Endpoint Agents Transfer"],"__originalOperationId":"transferEndpointAgents","security":[{"BearerAuth":[]}],"method":"post","path":"/endpoint/agents/transfer/bulk"}}