Overview
POST/integrations/connectintegrations

Connect an integration (polymorphic by auth method)

Finishes any auth method's connect flow and persists the connection under the target ecosystem `ecosystemId` the client names; the caller must manage it (404/403 otherwise). Returns the redacted connection (tokens never echoed).

Auth: bearerAuth — calls run as the authenticated user.

Request body

application/json · optional

  • type"oauth"
  • providerIdstring
  • serviceTypestring
  • ecosystemIdstring

    Target ecosystem id (the caller must manage it)

  • codestring

    OAuth authorization code

  • redirectUristring
  • statestring

    The HMAC-signed state returned by the auth-url endpoint (CSRF)

Example
{
  "type": "oauth",
  "providerId": "string",
  "serviceType": "string",
  "ecosystemId": "string",
  "code": "string",
  "redirectUri": "string",
  "state": "string"
}
Responses
200

Connected (redacted)

  • idstring
  • providerstring

    Provider slug (e.g. google-calendar, github)

  • serviceTypestring

    Service within the provider (e.g. calendar)

  • statusstring

    active | error | revoked | pending

  • displayNamestring
  • usernamestring
  • externalAccountIdstring

    Provider-side account id

  • lastSyncAtoptionalstring?

    Last successful sync (null = never)

  • lastErroroptionalstring?

    Last recorded sync error

  • createdAtstring
  • syncSettingsoptionalobject?

    Caller-tunable sync settings (gmailLabelIds / redditSubreddits / …) — non-secret, returned so settings forms can prefill instead of blind-overwriting.

Example
{
  "id": "string",
  "provider": "string",
  "serviceType": "string",
  "status": "string",
  "displayName": "string",
  "username": "string",
  "externalAccountId": "string",
  "lastSyncAt": "string",
  "lastError": "string",
  "createdAt": "string",
  "syncSettings": {}
}
400

Problem Details (RFC 9457)

  • typeoptionalstring

    URI identifying the problem type; 'about:blank' when unspecified

  • titlestring

    Short, human-readable summary of the problem type

  • statusinteger

    HTTP status code, duplicated in the body

  • detailoptionalstring

    Explanation specific to this occurrence

  • instanceoptionalstring

    URI reference for this occurrence (the request path)

Example
{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}
401

Problem Details (RFC 9457)

  • typeoptionalstring

    URI identifying the problem type; 'about:blank' when unspecified

  • titlestring

    Short, human-readable summary of the problem type

  • statusinteger

    HTTP status code, duplicated in the body

  • detailoptionalstring

    Explanation specific to this occurrence

  • instanceoptionalstring

    URI reference for this occurrence (the request path)

Example
{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}
403

Problem Details (RFC 9457)

  • typeoptionalstring

    URI identifying the problem type; 'about:blank' when unspecified

  • titlestring

    Short, human-readable summary of the problem type

  • statusinteger

    HTTP status code, duplicated in the body

  • detailoptionalstring

    Explanation specific to this occurrence

  • instanceoptionalstring

    URI reference for this occurrence (the request path)

Example
{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}
404

Problem Details (RFC 9457)

  • typeoptionalstring

    URI identifying the problem type; 'about:blank' when unspecified

  • titlestring

    Short, human-readable summary of the problem type

  • statusinteger

    HTTP status code, duplicated in the body

  • detailoptionalstring

    Explanation specific to this occurrence

  • instanceoptionalstring

    URI reference for this occurrence (the request path)

Example
{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}
Code examples
cURL
curl -X POST "https://api.agenticdeveloperhub.com/integrations/connect" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "type": "oauth",
  "providerId": "string",
  "serviceType": "string",
  "ecosystemId": "string",
  "code": "string",
  "redirectUri": "string",
  "state": "string"
}'
JavaScript
const res = await fetch("https://api.agenticdeveloperhub.com/integrations/connect", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/json"
  },
  body: "{\n  \"type\": \"oauth\",\n  \"providerId\": \"string\",\n  \"serviceType\": \"string\",\n  \"ecosystemId\": \"string\",\n  \"code\": \"string\",\n  \"redirectUri\": \"string\",\n  \"state\": \"string\"\n}",
});
const data = await res.json();