---
title: "Create an agent"
method: POST
path: "/v1/agents"
tags: ["Agents"]
---

# Create an agent

`POST /v1/agents`

Use this endpoint to create a new agent.

## Request body

- object
  - `name` string, required — Name of the new agent. Validation: It may contain any alphanumeric character, spaces, and the following special characters, `-`, `_`, `+`, `.`, `/`.
  - `description` string — Description of the new agent. It may contain any alphanumeric character, spaces, line breaks, and the following special characters, `-`, `_`, `+`, `.`, `/`.
  - `type` 'file-log' | 'empower' | 'unicorn' | 'labx' | 'chromeleon' | 'user-defined', required — Type of the new agent. The valid types are `file-log`, `empower`, `unicorn`, `labx`, `chromeleon` or `user-defined`.
  - `sourceType` string — Source Type of a user-defined agent. For a user-defined agent, it may contain any lower-case alphanumeric character, spaces, and the following special characters, `-`, `_`, `+`, `.`, `/`. However, a space can't be the first character. For other agent types it must be empty, null or not present
  - `integrationType` 'api' | 'datahub', required — New agent's integration type. The valid types are `api` or `datahub`.
  - `integrationId` string, uuid, required — Id of the connector to be used by the new agent, in GUID format
  - `datahubId` string, uuid — Id of the Data Hub the new agent is using, in GUID format. It is required for integrations of type 'datahub'. It must be set to null, empty, or not present for integrations of type 'api'.
  - `tags` string[] — Tags to associate with the agent.
  - `metadata` object — Metadata to associate with the agent.
  - `labels` object — Labels to associate with the agent
    - `labelsToAdd` object[], required — Labels to add the agent
      - `name` string, required
      - `value` string, required

## Response `200`

Successful response with agent details

- object
  - `id` string, uuid — The ID of the agent.
  - `name` string — The name of the agent.
  - `description` string — The description of the agent.
  - `sourceType` string, nullable — The source type of the agent (nullable).
  - `type` string — The type of agent.
  - `integrationType` string — The integration type of the agent.
  - `integrationId` string, uuid — The integration ID of the agent.
  - `datahubId` string, uuid, nullable — The Data Hub ID of the agent (nullable).
  - `sourceId` string, uuid — The source ID of the agent.
  - `isEnabled` boolean — Indicates if the agent is enabled or not.
  - `tags` string[] — Tags associated with the agent.
  - `metadata` object — Metadata associated with the agent.
  - `config` FLAConfiguration — Agent configuration if available, null otherwise.
    - `group_user` object
      - `user_name` string — The Windows User service account used for managing folder and file access for the agent.
      - `password` string — A secure hash of the user's password.
    - `agent_configuration` object
      - `s3_direct_upload` boolean — Whether to enable direct upload of files and logs to S3.
      - `receive_commands` boolean — Whether the agent should receive and execute commands from TDP.
      - `destination_id` string, uuid — The Destination Id of the Agent, used in place of its own ID in datalake file keys.
      - `agent_id` string — The ID of the agent.
      - `org_slug` string — The slug of the organization.
      - `Authentication` string — A secure hash of the agent's authentication token.
      - `advanced_setting` object
        - `heart_beat_interval` integer — The interval in seconds for the agent to check its connection status.
        - `agent_log_upload_job_interval` integer — The interval in seconds for the agent to upload logs.
        - `compression_type` 'Zip' | 'SevenZip' — The compression type for the agent.
        - `retry_limit` integer — The number of times the agent will retry to upload a file before it stops attempting the upload.
        - `tdpApiUrlOverride` string — The URL of the TDP API
        - `validateAwsCertificate` boolean — Indicates whether to validate the AWS certificate or not.
        - `proxyUseCustom` boolean — Indicates whether to use a custom proxy or not.
        - `proxyHost` string — The host of the proxy, if one is set.
        - `proxyPort` integer — The port of the proxy, if one is set.
        - `proxyBypassList` string — The list of addresses to bypass the proxy.
        - `proxyUsername` string — The username for the proxy, if one is set.
        - `proxyPassword` string — A secure hash of the agent's authentication token.
        - `proxyUseSystem` boolean — Indicates whether to use the system proxy or not.
    - `services_enabled` string[] — The services enabled for the agent.
    - `services_configuration` object
      - `fileWatcher` object, required
        - `use_path_configuration` boolean, required — Indicates whether or not to use path-level configuration for start date and interval.
        - `paths` FLAFileWatcherPathConfigurationItem[]
          - `path` string, required — The path to watch.
          - `file_watch_mode` 'file' | 'folder', required — The file watch mode.
          - `source_type` string, required — The source type.
          - `interval` integer, required — The time in seconds the agent will monitor the files for changes before uploading. This also specifies the time between scans of the path.
          - `start_date` string, date, required — Files with a last modified date on or after the specified date will be scanned and uploaded.
          - `patterns` string[], required — Defines a list of [glob patterns](https://developers.tetrascience.com/docs/common-glob-pattern) to match files in the path.
          - `metadata` object — Custom metadata to associate with files in the path.
          - `tags` string — Comma-separated list of tags to associate with files in the path.
          - `labels` object[] — **FLA v4.3.0+**: Labels applied to files in the path
            - `name` string, required — The label name.
            - `value` string, required — The label value.
          - `archive` object — **FLA v4.3.0+**: Options for archival and deletion of files in the path after upload
            - `path` string, required — The location where files from this path will be archived
            - `wait_time` integer, required — Amount of time to wait before moving the source file to the archive path after uploading
            - `wait_time_unit` 'Minutes' | 'Hours' | 'Days', required — The unit for the wait_time
            - `archive_without_checksum` boolean — Determines if files uploaded by a previous agent version that have no checksum are archived or not.
            - `dry_run` boolean — Whether to perform a dry run
            - `delete` object — Options for deletion of files from the archive path
              - …
          - `fetch_os_created_user` boolean — Determines if the OS-created user metadata is retrieved and included as metadata on files in the path or not.
          - `symlink_behavior` 'Legacy' | 'Ignore' — **(For FLA v4.4.1 and higher only)** Specifies how the Agent handles symbolic links when file scanning.
    - `windows_scheduled_task` object
      - `enabled` boolean — Indicates whether the Windows scheduled task to ensure the agent service is running is enabled or not..
      - `time` string — The time of day when the Windows scheduled task is triggered.

## Other responses

- `400` — Bad Request.

---

[API](https://skmtc.net/tetrascience/apis/tetra-data-lake.md) · [All operations](https://skmtc.net/tetrascience/apis/tetra-data-lake/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/tetrascience/tetra-data-lake/revisions/0205e2bace53/schema)