Use Agent Factory REST APIs

Use REST APIs to integrate external applications with Agent Factory resources and supported agents.

Select an Authentication Method

Use one authentication method in each request. The supported method depends on the endpoint.

Authentication method	Use
Agent integration API key	Run the Custom Workflow, Data Analysis Agent, Deep Research RAG Agent, or RAG Agent associated with the key. The key cannot manage resources, list users, or run another agent.
HTTPS Basic Authentication	Call supported integration endpoints as an enabled local Agent Factory user. This method doesn’t accept an SSO or identity-provider password. User-list operations require an administrator.
Service Account API key	Automate scoped operations on behalf of an enabled Agent Factory user. Resource and agent requests require the X-AgentFactory-Target-User header with the user’s canonical userId.

Agent Factory applies the effective user’s existing ownership, sharing, grant, and resource authorization rules. For Basic Authentication, the authenticated local user is the effective user. For Service Account requests, the target user is the effective user.

Review Supported Operations

The integration APIs support these operations:

Resource	Supported operations	Required Service Account scope
Generative and embedding model configurations	Create, list, edit, and delete configurations.	models:manage
Database data sources	Create, list, edit the description, and delete sources.	datasources:manage
Web data sources	Create, list, edit the description and proxy settings, check endpoint connectivity, and delete sources.	datasources:manage
File data sources	Upload files in resumable chunks, view upload progress and directories, edit descriptions, cancel uploads, list sources, and delete sources.	datasources:manage
File and web data-source ingestion status	Check processing progress and readiness after source creation or file upload.	datasources:manage
REST API data sources	Create a source from an OpenAPI JSON specification, list and delete sources, and edit endpoint and parameter descriptions.	datasources:manage
Users	List Agent Factory users.	users:list
Supported agents	Run Custom Workflows, Data Analysis Agents, Deep Research RAG Agents, and RAG Agents.	agents:run

Custom Workflows must be published before an integration client can run them. REST API data source integration endpoints don’t support source-level edits or security and OAuth configuration. Configure REST API data source security in the existing user interface.

Manage the Service Account API Key

Each Agent Factory installation supports one active Service Account API key. The key uses the aas_<secret> format.

An enabled local administrator can generate the initial key over HTTPS by using Basic Authentication:

POST /agentFactory/v1/integrations/service-account/api-key

Agent Factory returns the raw key only when you generate or regenerate it. Store the key in an approved secret manager. Agent Factory stores a salted verifier in the application wallet instead of the raw key.

Use the active Service Account API key to regenerate or revoke it:

Action	Method and path	Result
Regenerate	POST /agentFactory/v1/integrations/service-account/api-key/regenerate	Returns a new raw key and immediately invalidates the previous key.
Revoke	DELETE /agentFactory/v1/integrations/service-account/api-key	Prevents the Service Account from authenticating subsequent REST calls.

Send the active key as Authorization: Bearer aas_<secret>. The regenerate and revoke endpoints don’t accept administrator Basic Authentication or the X-AgentFactory-Target-User header. If the active key is lost or revoked, use the Service Account container CLI to recover access.

Call an API With the Service Account

For resource and agent operations, send the active Service Account API key and the canonical target user:

curl -k --location 'https://<host_name>/agentFactory/v1/integrations/agents/<agent_id>/run' \
--header 'Authorization: Bearer aas_<secret>' \
--header 'X-AgentFactory-Target-User: <canonical_user_id>' \
--header 'Content-Type: application/json' \
--data '{"message":"what tools are available?"}'

The Service Account must have the agents:run scope. The target user must be enabled and authorized to run the requested agent. The user-list endpoint doesn’t require a target-user header because it doesn’t operate on behalf of a user.

Do not send multiple credential methods in one request. Don’t log, store in source control, or expose Service Account keys, agent integration keys, passwords, or other credentials.

Model Configuration API Reference

Model endpoints accept HTTPS Basic Authentication or Service Account authentication. They don’t accept resource-scoped agent integration API keys.

Service Account requests require the models:manage scope and the X-AgentFactory-Target-User header. Agent Factory evaluates model visibility and authorization as the effective user.

Method and path	Purpose
GET /agentFactory/v1/integrations/models/llms	List generative model configurations visible to the effective user.
POST /agentFactory/v1/integrations/models/llms	Create a generative model configuration.
PATCH /agentFactory/v1/integrations/models/llms/{name}	Edit a generative model configuration.
DELETE /agentFactory/v1/integrations/models/llms/{name}	Delete a generative model configuration.
GET /agentFactory/v1/integrations/models/embeddings	List embedding model configurations visible to the effective user.
POST /agentFactory/v1/integrations/models/embeddings	Create an embedding model configuration.
PATCH /agentFactory/v1/integrations/models/embeddings/{name}	Edit an embedding model configuration.
DELETE /agentFactory/v1/integrations/models/embeddings/{name}	Delete an embedding model configuration.

Send a JSON Model Request

Use JSON when the provider doesn’t require a credential file:

{
  "name": "automation-openai",
  "provider": "openai",
  "connectionDetails": {
    "model_id": "gpt-4.1-mini",
    "api_key": "<provider_api_key>"
  }
}

Send a Multipart Model Request

Use multipart/form-data when the provider requires a credential or certificate file.

Provider case	Form field
Google service account	files=@/path/to/service-account.json
OCI user principal	files=@/path/to/oci_api_key.pem
Oracle Private AI Services custom CA	ca_file=@/path/to/ca.pem

Common multipart fields are name, provider, and connectionDetails. Encode connectionDetails as a JSON object in the form field.

For Oracle Private AI Services, connectionDetails contains model_id, base_url, and an optional api_key. The optional ca_file must be a PEM or CRT file.

Data Source API Reference

Data source endpoints accept HTTPS Basic Authentication or Service Account authentication. They don’t accept resource-scoped agent integration API keys.

Service Account requests require the datasources:manage scope and the X-AgentFactory-Target-User header. Agent Factory evaluates data source visibility and authorization as the effective user.

List endpoints accept offset and limit. The defaults are offset=0 and limit=50. The offset must be nonnegative, and the limit must be between 1 and 500.

List responses contain items, count, and hasMore. The count field reports the number of items in the returned page.

Database Data Sources

Method and path	Purpose
GET /agentFactory/v1/integrations/datasources/databases?offset=0&limit=50	List database data sources available to the effective user.
POST /agentFactory/v1/integrations/datasources/databases	Create a database data source.
PATCH /agentFactory/v1/integrations/datasources/databases/{database_id}	Update the database description.
DELETE /agentFactory/v1/integrations/datasources/databases/{database_id}	Delete a database data source.

Use JSON for a direct host, port, and service connection:

{
  "sourceName": "automation database",
  "description": "Database created through automation",
  "host": "db.example.internal",
  "port": 1521,
  "service": "example_high",
  "username": "app_user",
  "password": "<database_password>"
}

The sourceName value can contain only letters, numbers, and spaces.

Use multipart/form-data for an Autonomous AI Database wallet connection.

Form field	Required	Description
sourceName	Yes	Name containing only letters, numbers, and spaces.
description	No	Data source description.
connectionType	Yes	Value wallet.
username	Yes	Database user.
password	Yes	Database password.
tnsAlias	Yes	Alias from the wallet’s tnsnames.ora file.
wallet	Yes	Wallet .zip archive file.

Web Data Sources

Method and path	Purpose
GET /agentFactory/v1/integrations/datasources/web?offset=0&limit=50	List web data sources available to the effective user.
POST /agentFactory/v1/integrations/datasources/web	Create a web data source.
PATCH /agentFactory/v1/integrations/datasources/web/{source_id}	Update the description and optional proxy settings.
DELETE /agentFactory/v1/integrations/datasources/web/{source_id}	Delete a web data source.
POST /agentFactory/v1/integrations/datasources/web/test	Check endpoint connectivity by using an optional proxy.

Use this JSON structure to create a web data source:

{
  "sourceName": "automation website",
  "description": "Website content for automation",
  "endpoint": "https://docs.example.com",
  "crawlType": "WEB",
  "depth": 2,
  "frequency": 24,
  "crawl_type_specific_config": {
    "include_filters": [],
    "exclude_filters": [],
    "exclude_file_extensions": [],
    "proxy_url": null
  }
}

• sourceName must contain only letters, numbers, and spaces and must be 3 through 200 characters long.
• description is required and must be 1 through 250 characters long.
• crawlType is optional and defaults to WEB. No other value is accepted.
• depth accepts 0 through 10, or -1 for unlimited depth. The default is -1.
• frequency is required and is expressed in hours, between 2.4 and 193536 hours. This range is equivalent to 0.1 through 8064 days.
• Crawl configuration is optional. Filters default to empty lists, and the proxy defaults to no proxy.
• Endpoint and proxy URLs must satisfy the configured outbound URL security policy.

A successful create response uses 201 Created and returns success and sourceId.

The edit endpoint accepts only description and proxyUrl:

{
  "description": "Updated website description",
  "proxyUrl": "http://proxy.example.com:8080"
}

The description field is required. Omit proxyUrl to preserve the current proxy, or use null or an empty string to clear it.

Use the test endpoint to check connectivity without creating a data source:

{
  "url": "https://docs.example.com",
  "proxy": null
}

The response contains success, which indicates whether the endpoint returned HTTP 200.

File Data Sources

Method and path	Purpose
GET /agentFactory/v1/integrations/datasources/files?offset=0&limit=50	List file data sources available to the effective user.
POST /agentFactory/v1/integrations/datasources/files	Create data source metadata and initialize a chunk-upload session.
PATCH /agentFactory/v1/integrations/datasources/files/{source_id}	Update the description.
DELETE /agentFactory/v1/integrations/datasources/files/{source_id}	Delete the file data source and its stored directory.
GET /agentFactory/v1/integrations/datasources/files/{source_id}/tree?offset=0&limit=50	List directory-tree entries for the source.
POST /agentFactory/v1/integrations/datasources/files/upload-sessions/{session_id}/chunk	Upload one file chunk.
GET /agentFactory/v1/integrations/datasources/files/upload-sessions/{session_id}	Retrieve upload status, progress, and received or missing chunk indexes.
DELETE /agentFactory/v1/integrations/datasources/files/upload-sessions/{session_id}	Cancel the upload session.

Initialize an upload with source metadata and one or more file declarations:

{
  "metadata": {
    "sourceName": "automation documents",
    "description": "Documents uploaded through automation"
  },
  "files": [
    {
      "name": "guide.pdf",
      "size": 1048576,
      "chunks": 2,
      "mime_type": "application/pdf"
    }
  ]
}

• sourceName must contain only letters, numbers, and spaces and must be 3 through 200 characters long.
• description is required and must be 1 through 250 characters long.
• Each file requires name, size in bytes, and a positive chunks count. The mime_type field is optional.
• Supported extensions are PDF, TXT, DOC, DOCX, HTML, HTM, and PPTX.
• The declared size must not exceed 1000000000 bytes for each file.
• File names must not contain paths and must remain unique after filename sanitization.
• Agent Factory determines server-side upload paths and ownership.
• The source uses unlimited depth and disables periodic refresh, matching the file-source creation defaults.

A successful response uses 201 Created. It returns sourceId, upload_session_id, and file records that contain their assigned file_id values.

Upload each chunk by using multipart/form-data:

Form field	Required	Description
file_id	Yes	File identifier returned when the session was initialized.
chunk_index	Yes	Zero-based chunk index that is less than the declared chunk count.
chunk	Yes	Binary contents of the chunk.

Upload-session operations require the effective user who owns the session. When all files are uploaded, Agent Factory assembles the files and finalizes the source through the existing ingestion workflow.

Use the session-status endpoint to retrieve progress and determine which chunks remain. Upload completion and ingestion readiness are separate states.

The file data source edit endpoint accepts only the description field.

REST API Data Sources

Method and path	Purpose
GET /agentFactory/v1/integrations/datasources/rest-apis?offset=0&limit=50	List REST API data sources and their tool details.
POST /agentFactory/v1/integrations/datasources/rest-apis	Create a REST API data source from an OpenAPI JSON specification.
DELETE /agentFactory/v1/integrations/datasources/rest-apis/{source_id}	Delete a REST API data source.
PATCH /agentFactory/v1/integrations/datasources/rest-apis/{source_id}/endpoints/{endpoint_id}	Update an endpoint description.
PATCH /agentFactory/v1/integrations/datasources/rest-apis/{source_id}/endpoints/{endpoint_id}/parameters	Update a parameter description.

Create a data source by using multipart/form-data:

Form field	Required	Description
files	Yes	One OpenAPI or Swagger JSON specification with a .json extension, up to 5 MiB.
sourceName	No	Name that overrides the source name extracted from the specification.
description	No	Description that overrides the source description extracted from the specification.

Agent Factory processes the specification with its existing OpenAPI parser. A successful response uses 201 Created and returns success, sourceId, endpointsLoaded, and warnings.

Use this request body to update an endpoint description:

{
  "description": "Returns the available customers"
}

Use this request body to update a parameter description:

{
  "param_name": "customerId",
  "param_description": "Identifier of the customer to retrieve"
}

The endpoint must belong to the specified source, and the named parameter must exist on that endpoint. Configure REST API data source security and OAuth in the existing user interface.

Data Source Ingestion Status

Use these endpoints to check processing progress and readiness for file and web data sources:

Method and path	Purpose
GET /agentFactory/v1/integrations/datasources/files/{source_id}/ingestion-status	Get file data-source ingestion status.
GET /agentFactory/v1/integrations/datasources/web/{source_id}/ingestion-status	Get web data-source ingestion status.

Pass the canonical source_id returned by data-source creation or listing. For a file upload, use the sourceId returned by upload-session status after the source is available. The request has no body or pagination parameters. Upload-session status tracks the file transfer; ingestion status tracks processing after upload.

These endpoints accept the data-source authentication methods described above. A Service Account caller needs the datasources:manage scope and X-AgentFactory-Target-User. The effective user must have use permission on the data source.

A successful request returns HTTP 200 with these fields:

Field	Type	Description
sourceId	string	Data-source identifier.
sourceType	string	file or web.
status	string	PENDING, RUNNING, FAILED, or COMPLETED.
ready	boolean	true only when status is COMPLETED.
currentStage	string or null	Processing stage, when available: CRAWLING, STORING_CONTENT, CHUNKING, EMBEDDING, or INDEXING.
lastRefreshAt	string or null	Recorded last-refresh time, when available.
errorMessage	string or null	Recorded ingestion error, when available.

PENDING is also returned when no state has been recorded. A request reports the current state; it does not start ingestion or wait for completion. Repeat the GET request at an appropriate interval. Authentication failures return HTTP 401; insufficient scope, delegation, or data-source access returns HTTP 403; a missing source, type mismatch, or missing ingestion record returns HTTP 404.

{
  "sourceId": "123",
  "sourceType": "file",
  "status": "RUNNING",
  "ready": false,
  "currentStage": "EMBEDDING",
  "lastRefreshAt": null,
  "errorMessage": null
}

User Listing API Reference

Use GET /agentFactory/v1/integrations/users to list Agent Factory users.

Local HTTPS Basic callers require administrator privileges. Service Account callers require the users:list scope but don’t require X-AgentFactory-Target-User. Resource-scoped agent integration API keys are not accepted.

A successful request returns 200 OK and a response similar to this example:

{
  "items": [
    {
      "userId": "[e-mail]",
      "email": "[e-mail]",
      "role": "Administrator",
      "status": "Enabled",
      "userTypeId": 0,
      "lastLogin": "2026-09-22T20:00:00",
      "joined": "2026-09-01T10:00:00"
    }
  ],
  "count": 1
}

Agent Execution API Reference

Use POST /agentFactory/v1/integrations/agents/{agent_id}/run to run Custom Workflows, Data Analysis Agents, Deep Research RAG Agents, and RAG Agents.

Authenticate with a resource-scoped agent integration API key, local HTTPS Basic credentials, or a Service Account API key. The agent integration key must be bound to the requested agent.

Service Account execution requires the agents:run scope and X-AgentFactory-Target-User. The effective user remains subject to the existing agent, room, resource, and model authorization rules.

Request body field	Type	Required	Description
message	string	Yes	Prompt sent to the agent.
roomId	string	No	Existing room that is subject to the selected agent’s authorization rules.

POST /agentFactory/v1/integrations/agents/4C3AA2107ECC409CE0636402000A600/run
Authorization: Bearer afk_<prefix>_<secret>
Content-Type: application/json
Accept: application/json

{"message":"What is the capital of Argentina?"}

Execution Authorization

Before dispatching the request, Agent Factory verifies these conditions:

1. The caller has valid integration credentials.
2. The requested agent exists and is a supported type.
3. A requested Custom Workflow is published.
4. The effective user can access the agent, room, resources, and models.
5. An agent integration key is valid and bound to the requested agent.
6. A Service Account key is active and has the agents:run scope.
7. The Service Account target user exists, is enabled, and can run the agent.

A resource-scoped key authorizes only its associated agent. Local Basic-authenticated users and Service Account target users can run only agents that they are otherwise authorized to use.

Successful Agent Responses

The integration endpoint returns the corresponding native agent response.

Agent family	Typical response fields
Custom Workflow	message, roomId
Data Analysis	message, optional structured data, and roomId
Deep Research	Disclaimer, message, roomId, sources, and suggestions
Knowledge	Disclaimer, message, roomId, suggestions, and sources when retrieved documents provide citations

RAG Agent sources entries use this structure:

{
  "sources": [
    {
      "title": "What Is the Redo Log?",
      "uri": "https://docs.oracle.com/example",
      "rank": 1
    }
  ]
}

REST API Error Reference

Integration-specific errors use this structure:

{
  "error": {
    "code": "DATABASE_CONNECTION_FAILED",
    "message": "Unable to connect to the database with the supplied details."
  }
}

HTTP status	Error code or type	When returned
400	LLM_REQUEST_INVALID	The LLM request body is invalid.
400	LLM_CONNECTION_TEST_FAILED	The LLM provider connection test didn’t succeed.
400	DATABASE_REQUEST_INVALID	The database request or source name is invalid.
400	DATABASE_CONNECTION_INVALID	The database connection details are invalid.
400	DATABASE_CONNECTION_FAILED	The database connection or ping failed.
400	DATASOURCE_REQUEST_INVALID	A data source request, upload, specification, or URL configuration is invalid.
400	INTEGRATION_AGENT_NOT_PUBLISHED	The Custom Workflow isn’t published.
400	Service Account request error	The target-user header is missing, repeated, invalid, or supplied to a key-management endpoint.
401	HTTP authentication error	Integration credentials are missing, invalid, or conflicting.
401	Agent integration API-key authentication error	The key is invalid, inactive, expired, or associated with an inactive execution identity.
401	Service Account authentication error	The aas_... key is missing, malformed, revoked, replaced, or doesn’t match the stored verifier.
401	Service Account administrator authentication error	Initial REST key-generation credentials are missing or invalid.
403	Authorization error	The effective user lacks required resource, agent, or administrator permission.
403	Agent integration API-key authorization error	The key can’t run the requested agent, lacks run permission, or supplies a target-user header.
403	DATASOURCE_ACCESS_DENIED	The effective user lacks permission for the requested data source operation.
403	Service Account administrator authorization error	The initial key-generation caller isn’t an enabled local administrator.
403	Service Account scope error	The Service Account lacks models:manage, datasources:manage, agents:run, or users:list for the request.
403	Service Account target authorization error	The target user is missing, inactive, or lacks authorization for the requested operation.
404	INTEGRATION_AGENT_NOT_FOUND or resource-not-found error	The requested agent or resource doesn’t exist.
404	DATASOURCE_NOT_FOUND	The requested data source, REST endpoint, or REST parameter wasn’t found.
404	UPLOAD_SESSION_NOT_FOUND	The upload session is missing or inaccessible, or isn’t a data source upload session.
409	DATASOURCE_CONFLICT	A data source or upload exists, or a uniqueness constraint prevents the operation.
413	DATASOURCE_UPLOAD_TOO_LARGE	The REST API specification exceeds the 5 MiB upload limit.
422	Request validation error	Request fields, pagination parameters, or multipart fields fail FastAPI validation.
500	DATASOURCE_OPERATION_FAILED	An unexpected data source operation failure occurred.
503	Service Account authentication unavailable	The active Service Account configuration can’t be read or validated.

Authentication and FastAPI validation errors can use the framework’s detail response structure. After integration authentication succeeds, native agent handlers retain their existing error contracts.