Test a Workspace Connection

POST

/api/app/{app_slug}/workflow/connections/{connection_id}/test/

curl --request POST \
  --url https://api.agentaab.com/api/app/example/workflow/connections/example/test/ \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{}'

Test the stored credential through the bounded provider adapter and atomically record sanitized test state and capabilities. The request body must be an empty object.

Authorizations

• creatorBearerAuth
• creatorSessionCookieAuth

Parameters

Path Parameters

app_slug

required

string

connection_id

required

string

<= 128 characters

Request Body^required

Media typeapplication/json

object

Example^generated

{}

Responses

200

The tested redacted Connection summary with sanitized cached capabilities.

Media typeapplication/json

object

connection

required

Redacted Workspace Connection state. It contains a server-managed reference and sanitized capabilities, never private credential material.

object

id

required

string

credential_ref

required

Opaque server-managed reference used by materialized v1 Tool bindings.

string

/^WORKSPACE_CONNECTION_[A-F0-9]{32}$/

scope

required

object

kind

required

string

Allowed values: creator organization

id

required

string

provider

required

string

Allowed values: web_search mcp

display_name

required

string

endpoint

required

string format: uri

nullable

configuration

required

Bounded provider configuration with credential-shaped fields forbidden.

object

key

additional properties

any

credential_mode

required

string

Allowed values: bearer x_api_key

cached_capabilities

required

Sanitized bounded capability marker or MCP Tool manifest from the last successful test.

object

key

additional properties

any

status

required

string

Allowed values: active error deleted

last_tested_at

required

string format: date-time

nullable

last_error_code

required

string

nullable

Allowed values: workspace_connection_test_required workspace_connection_auth_unavailable workspace_connection_provider_unavailable

created_at

required

string format: date-time

updated_at

required

string format: date-time

rotated_at

required

string format: date-time

nullable

deleted_at

required

string format: date-time

nullable

Example

{
  "connection": {
    "scope": {
      "kind": "creator"
    },
    "provider": "web_search",
    "credential_mode": "bearer",
    "status": "active",
    "last_error_code": "workspace_connection_test_required"
  }
}

400

The request body is not an exact empty object.

Media typeapplication/json

object

error

required

string

code

required

Stable public-safe Workspace Connection error identifier.

string

Allowed values: workspace_connection_failed workspace_connection_invalid workspace_connection_unavailable workspace_connection_conflict workspace_connection_capacity_exceeded workspace_connection_encryption_unavailable workspace_connection_decryption_failed workspace_connection_store_unavailable workspace_connection_mutations_disabled workspace_connection_payload_too_large workspace_connection_creation_not_found workspace_connection_test_failed workspace_connection_test_state_unavailable

Example

{
  "code": "workspace_connection_failed"
}

401

The creator session is missing, invalid, expired, or does not have a verified email.

Media typeapplication/json

object

error

required

string

code

required

string

Allowed values: creator_session_required creator_email_unverified creator_session_invalid creator_session_expired

Example

{
  "code": "creator_session_required"
}

403

A public Agent Business runtime credential cannot access creator control-plane APIs.

Media typeapplication/json

object

error

required

string

code

required

string

Allowed values: runtime_token_not_allowed

Example

{
  "code": "runtime_token_not_allowed"
}

404

The Workflow or Connection is unavailable or not mutable by this caller.

Media typeapplication/json

One of:

object

object

error

required

string

code

required

string

Allowed values: application_unavailable

object

object

error

required

string

code

required

Stable public-safe Workspace Connection error identifier.

string

Allowed values: workspace_connection_failed workspace_connection_invalid workspace_connection_unavailable workspace_connection_conflict workspace_connection_capacity_exceeded workspace_connection_encryption_unavailable workspace_connection_decryption_failed workspace_connection_store_unavailable workspace_connection_mutations_disabled workspace_connection_payload_too_large workspace_connection_creation_not_found workspace_connection_test_failed workspace_connection_test_state_unavailable

Example

{
  "code": "application_unavailable"
}

409

The Agent Business is not a Workflow, the creator identity conflicts, or a concurrent Connection mutation invalidated this test result.

Media typeapplication/json

One of:

object

object

error

required

string

code

required

string

Allowed values: application_not_workflow

object

object

error

required

string

code

required

string

Allowed values: creator_identity_conflict

object

object

error

required

string

code

required

Stable public-safe Workspace Connection error identifier.

string

Allowed values: workspace_connection_failed workspace_connection_invalid workspace_connection_unavailable workspace_connection_conflict workspace_connection_capacity_exceeded workspace_connection_encryption_unavailable workspace_connection_decryption_failed workspace_connection_store_unavailable workspace_connection_mutations_disabled workspace_connection_payload_too_large workspace_connection_creation_not_found workspace_connection_test_failed workspace_connection_test_state_unavailable

Example

{
  "code": "application_not_workflow"
}

413

The bounded request exceeds 96 KiB.

Media typeapplication/json

object

error

required

string

code

required

Stable public-safe Workspace Connection error identifier.

string

Allowed values: workspace_connection_failed workspace_connection_invalid workspace_connection_unavailable workspace_connection_conflict workspace_connection_capacity_exceeded workspace_connection_encryption_unavailable workspace_connection_decryption_failed workspace_connection_store_unavailable workspace_connection_mutations_disabled workspace_connection_payload_too_large workspace_connection_creation_not_found workspace_connection_test_failed workspace_connection_test_state_unavailable

Example

{
  "code": "workspace_connection_failed"
}

500

An unexpected Workspace Connection failure was sanitized before returning it.

Media typeapplication/json

object

error

required

string

code

required

string

Allowed values: workspace_connection_failed

Example

{
  "code": "workspace_connection_failed"
}

502

Creator session verification or Connection provider/credential verification failed. Raw upstream failures are not returned.

Media typeapplication/json

One of:

object

object

error

required

string

code

required

string

Allowed values: creator_session_verification_failed

object

object

error

required

string

code

required

Stable public-safe Workspace Connection error identifier.

string

Allowed values: workspace_connection_failed workspace_connection_invalid workspace_connection_unavailable workspace_connection_conflict workspace_connection_capacity_exceeded workspace_connection_encryption_unavailable workspace_connection_decryption_failed workspace_connection_store_unavailable workspace_connection_mutations_disabled workspace_connection_payload_too_large workspace_connection_creation_not_found workspace_connection_test_failed workspace_connection_test_state_unavailable

Example

{
  "code": "creator_session_verification_failed"
}

503

Creator auth, control-plane storage, mutation, credential decryption, outbound policy, or atomic test-state storage is unavailable.

Media typeapplication/json

One of:

object

object

error

required

string

code

required

string

Allowed values: creator_auth_provider_invalid creator_session_not_configured creator_control_storage_not_configured

object

object

error

required

string

code

required

string

Allowed values: workspace_connection_encryption_unavailable workspace_connection_decryption_failed workspace_connection_store_unavailable workspace_connection_mutations_disabled workspace_connection_test_state_unavailable

Example

{
  "code": "creator_auth_provider_invalid"
}