> ## Documentation Index > Fetch the complete documentation index at: https://docs.engini.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create an on-premise agent. > The response carries the agent's token - the live credential it uses to authenticate to the task service - so a machine can provision a box in one round-trip. Callers who would rather not have it in shell history can omit it here and read it later from GET /v1/opa-agents/{id}/token. Each setting is range-checked against what this agent's connector declares it accepts - currently parallelTasks 1-100 and pullPeriodSeconds 10-9999999, the same bounds the Engini UI enforces. An out-of-range value is a 400 naming each offending field, and persists nothing. Note the DTO summaries in the published Engini.Models package still say "Minimum 1" for both; the bounds enforced here are the connector's own metadata. ## OpenAPI ````yaml /api-reference/openapi.json post /v1/opa-agents openapi: 3.0.0 info: title: Engini DeveloperAPI version: v1 description: 'Merged public developer API spec: Identity + WorkflowApi.' servers: - url: https://api.engini.io security: - Bearer: [] - ApiKey: [] tags: - name: Auth description: Identify the caller a Developer API request is authenticated as. - name: Applications description: >- Discover the applications (toolkits) available in Engini and their connection requirements. - name: Tools description: Browse and execute the tools exposed by Engini applications. - name: Toolsets description: Manage toolsets - named groupings of connections and tools. - name: McpServers description: >- Inspect and maintain MCP servers - the account-wide endpoints that expose Engini tools and workflows over the Model Context Protocol. Distinct from the MCPClient connection kind, which is Engini consuming a third-party MCP server. - name: Connections description: >- Manage connections to applications, including OAuth sign-in and default-connection selection. - name: Triggers description: >- Create triggers that fire when something changes in a connected app, and manage the destinations their events are delivered to. paths: /v1/opa-agents: post: tags: - OpaAgents summary: Create an on-premise agent. description: >- The response carries the agent's token - the live credential it uses to authenticate to the task service - so a machine can provision a box in one round-trip. Callers who would rather not have it in shell history can omit it here and read it later from GET /v1/opa-agents/{id}/token. Each setting is range-checked against what this agent's connector declares it accepts - currently parallelTasks 1-100 and pullPeriodSeconds 10-9999999, the same bounds the Engini UI enforces. An out-of-range value is a 400 naming each offending field, and persists nothing. Note the DTO summaries in the published Engini.Models package still say "Minimum 1" for both; the bounds enforced here are the connector's own metadata. operationId: OpaAgents_CreateAgent parameters: [] requestBody: x-name: request description: >- The agent creation payload. name is required; each omitted setting takes its own default (2 parallel tasks, 10s pull, Information). content: application/json: schema: $ref: '#/components/schemas/CreateOpaAgentRequest' required: true x-position: 1 responses: '200': description: The newly created agent, including its token. content: application/json: schema: $ref: '#/components/schemas/OpaAgentCreateResponse' '400': description: Bad request - malformed body or invalid parameters. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '401': description: Unauthorized - missing or invalid bearer token. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: Forbidden - the caller lacks access to the resource. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found - the resource does not exist. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '429': description: Too many requests - rate limit exceeded. headers: Retry-After: description: Number of seconds to wait before retrying. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '500': description: Internal server error - an unexpected error occurred. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' security: - Bearer: [] - ApiKey: [] components: schemas: CreateOpaAgentRequest: type: object description: Request body for creating an on-premise agent. additionalProperties: false required: - name properties: name: type: string description: >- Display name for the new agent. Required - declared non-nullable so RequiredPropertiesSchemaProcessor marks it required in the OpenAPI document and the generated client rejects an omitted name before the round-trip. description: type: string description: Optional description of the agent. nullable: true applicationSlug: type: string description: >- Which on-premise agent application to create under. Only needed when more than one exists - the 409 OPA_APPLICATION_AMBIGUOUS response lists the candidate slugs in its details so this can be retried with one of them. nullable: true settings: description: >- Optional runtime settings. Each member defaults independently when omitted: 2 parallel tasks, 10s pull, Information. nullable: true oneOf: - $ref: '#/components/schemas/OpaAgentSettings' OpaAgentCreateResponse: allOf: - $ref: '#/components/schemas/OpaAgentDetail' - type: object description: >- Response for agent creation. Carries the token so a caller can provision a box in one round-trip. The token is a live credential - callers who would rather not have it in shell history should read it later from GET /v1/opa-agents/{id}/token instead. additionalProperties: false properties: token: type: string description: The newly minted agent token. ErrorResponse: type: object description: >- Unified error envelope for every non-200 response from /api/DeveloperAPI/v1/*. See applications-tools-spec.md ยง"Error envelope". additionalProperties: false required: - errorCode - message - requestId - timestamp - path properties: errorCode: type: string description: Machine-readable error code identifying the failure. message: type: string description: Human-readable error message. requestId: type: string description: Identifier of the request, for support/correlation. timestamp: type: string description: Timestamp when the error occurred (ISO 8601). path: type: string description: Request path that produced the error. details: type: array description: Per-field validation details, when applicable. nullable: true items: $ref: '#/components/schemas/ErrorDetail' OpaAgentSettings: type: object description: >- Runtime settings of an on-premise agent. Stored as Connector.Key1/Key2/Key3. additionalProperties: false properties: parallelTasks: type: integer description: >- How many tasks the agent runs concurrently. Currently 1-100. Null in a request leaves it unchanged. The accepted range is declared by the agent connector rather than fixed here, and a value outside it is rejected with 400 rather than clamped. format: int32 nullable: true pullPeriodSeconds: type: integer description: >- Seconds the agent waits between task polls. Currently a minimum of 10. Null in a request leaves it unchanged. The accepted range is declared by the agent connector rather than fixed here, and a value outside it is rejected with 400 rather than clamped. format: int32 nullable: true logLevel: type: string description: >- Log level the agent writes at, for example "Information". Null in a request leaves it unchanged. nullable: true OpaAgentDetail: allOf: - $ref: '#/components/schemas/OpaAgentListItem' - type: object description: Full detail for one on-premise agent. additionalProperties: false properties: settings: description: Runtime settings currently stored for the agent. oneOf: - $ref: '#/components/schemas/OpaAgentSettings' appliedToAgent: type: boolean description: >- False when a settings write reached the database but not the agent, because the agent was Offline. Null on reads - only set by update responses. nullable: true dispatchedTaskIds: type: array description: >- Cloud task identifiers dispatched to the live agent by a settings write. Empty when offline. nullable: true items: type: string ErrorDetail: type: object description: A single field-level error detail within an ErrorResponse. additionalProperties: false required: - field - issue properties: field: type: string description: Name of the field the issue relates to. issue: type: string description: Description of the issue with the field. OpaAgentListItem: type: object description: One On-Premise Agent as it appears in a list response. additionalProperties: false required: - agentId - status - createdBy - createdDate properties: agentId: type: integer description: Identifier of the agent. format: int32 name: type: string description: Display name of the agent. nullable: true description: type: string description: Optional description of the agent. nullable: true status: type: string description: >- Liveness of the agent: WaitingForConnection, Online, Offline or Disabled. version: type: string description: Version the agent last self-reported. Null until it first connects. nullable: true lastSeenAt: type: string description: >- Last heartbeat received from the agent. Null when it has never connected. format: date-time nullable: true createdBy: type: string description: Identifier of the user who created the agent. format: uuid createdDate: type: string description: When the agent was created. format: date-time updatedBy: type: string description: Identifier of the user who last updated the agent. format: uuid nullable: true updatedDate: type: string description: When the agent was last updated. format: date-time nullable: true securitySchemes: Bearer: type: http description: Enter your JWT token scheme: bearer bearerFormat: JWT ApiKey: type: apiKey description: >- Opaque Developer API key (prefix `eng_`). Authenticates as the key's owner and resolves the account automatically. name: x-api-key in: header ````