{
  "openapi": "3.1.0",
  "info": {
    "title": "Agent OS Context API",
    "version": "1.0.0",
    "description": "Search your users' synced content and read the text around a search result."
  },
  "servers": [
    {
      "url": "https://agentos.useparagon.com",
      "description": "Production US Cloud"
    },
    {
      "url": "https://agentos.eu.paragon.so",
      "description": "Production EU Cloud"
    }
  ],
  "security": [{ "bearerAuth": [] }],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT",
        "description": "Your [Paragon User Token](/getting-started/installing-the-connect-sdk#setup) (JWT), which you can generate using your project's signing keys."
      },
      "apiKeyAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "A Paragon API key (starting with `api_key_`) that has the Setup Links API scope. Create one in the Paragon dashboard."
      }
    },
    "parameters": {
      "ProjectId": {
        "name": "projectId",
        "in": "path",
        "required": true,
        "schema": { "type": "string", "format": "uuid" },
        "description": "Your Paragon Project ID. Must match the Project ID in your Paragon User Token."
      }
    },
    "schemas": {
      "CreateSetupLinkRequest": {
        "type": "object",
        "properties": {
          "endUserId": {
            "type": "string",
            "description": "The Connected User the Setup Link is for. Required when you authenticate with an API key. When you authenticate with a Paragon User Token, it must match the token's `sub` claim, and defaults to it when omitted."
          },
          "expiresIn": {
            "type": "integer",
            "minimum": 1,
            "maximum": 86400,
            "default": 3600,
            "description": "How long the link stays valid, in seconds. Values above 86400 (24 hours) are capped at 86400."
          },
          "integrations": {
            "type": "array",
            "items": { "type": "string" },
            "description": "Limit the link to these integrations, using the same type names as the Connect SDK (for example, `googledrive`). Every integration must be enabled for the project. Omit to allow all enabled integrations."
          }
        }
      },
      "CreateSetupLinkResponse": {
        "type": "object",
        "required": ["url", "expiresAt"],
        "properties": {
          "url": {
            "type": "string",
            "description": "The hosted Setup Link URL to send to your user. The URL carries a signed token, so treat it like a credential."
          },
          "expiresAt": {
            "type": "string",
            "format": "date-time",
            "description": "When the link expires, as an ISO 8601 timestamp."
          }
        }
      },
      "SetupLinkError": {
        "type": "object",
        "properties": {
          "code": {
            "type": "string",
            "description": "A numeric Paragon error code, such as `56003`."
          },
          "message": {
            "type": "string",
            "description": "A human-readable description of what went wrong."
          }
        }
      },
      "ContentSource": {
        "type": "string",
        "enum": [
          "onedrive",
          "sharepoint",
          "dropbox",
          "box",
          "confluence",
          "googledrive"
        ]
      },
      "CallerIdentityEntry": {
        "type": "object",
        "required": ["principal"],
        "properties": {
          "principal": {
            "type": "string",
            "maxLength": 1024,
            "description": "The user's email address or provider-specific user ID. If you pass a provider-specific ID instead of an email, you must also set source."
          },
          "source": {
            "$ref": "#/components/schemas/ContentSource",
            "description": "The source this account applies to."
          }
        }
      },
      "SearchRequest": {
        "type": "object",
        "required": ["query"],
        "additionalProperties": false,
        "properties": {
          "query": {
            "type": "string",
            "minLength": 1,
            "maxLength": 1024,
            "description": "The text to search for."
          },
          "sources": {
            "type": "array",
            "maxItems": 6,
            "items": { "$ref": "#/components/schemas/ContentSource" },
            "description": "Limit the search to these sources. If omitted, all sources are searched."
          },
          "syncIds": {
            "type": "array",
            "maxItems": 50,
            "items": { "type": "string", "format": "uuid" },
            "description": "Limit the search to these syncs. If omitted, all syncs are searched."
          },
          "topK": {
            "type": "integer",
            "minimum": 1,
            "maximum": 50,
            "default": 10,
            "description": "The maximum number of records to return."
          },
          "segmentsPerRecord": {
            "type": "integer",
            "minimum": 1,
            "maximum": 5,
            "default": 1,
            "description": "The maximum number of matching passages to return for each record."
          },
          "rerank": {
            "type": "boolean",
            "description": "Set to false to skip reranking the results."
          },
          "identity": {
            "description": "The account whose access applies. Pass a string to use one account on every source, or an array to use a different account for each source.",
            "oneOf": [
              { "type": "string", "maxLength": 1024 },
              {
                "type": "array",
                "minItems": 1,
                "maxItems": 20,
                "items": { "$ref": "#/components/schemas/CallerIdentityEntry" }
              }
            ]
          },
          "email": {
            "type": "string",
            "maxLength": 1024,
            "deprecated": true,
            "description": "Deprecated. Use identity instead."
          }
        }
      },
      "Segment": {
        "type": "object",
        "required": ["pointer", "chunkId", "text", "relevancy", "rerankScore"],
        "properties": {
          "pointer": {
            "type": "string",
            "description": "Pass this to Read Segment Context to read the text around this passage."
          },
          "chunkId": {
            "type": "string",
            "deprecated": true,
            "description": "Deprecated. Use pointer instead."
          },
          "text": {
            "type": "string",
            "description": "The text of the matching passage."
          },
          "relevancy": {
            "type": "number",
            "description": "Rank-based score used to order passages in this response. Not comparable across requests."
          },
          "rerankScore": {
            "oneOf": [{ "type": "number" }, { "type": "null" }],
            "description": "The reranker's score for this passage, or null if it was not reranked."
          }
        }
      },
      "SearchResult": {
        "type": "object",
        "required": [
          "id",
          "syncId",
          "source",
          "relevancy",
          "rerankScore",
          "segments",
          "generation"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique ID for this record, in the format {syncId}.{recordId}."
          },
          "syncId": {
            "type": "string",
            "description": "The ID of the sync this record belongs to."
          },
          "source": {
            "type": "string",
            "description": "The source this record came from, such as googledrive."
          },
          "relevancy": {
            "type": "number",
            "description": "Rank-based score used to order records in this response. Not comparable across requests."
          },
          "rerankScore": {
            "oneOf": [{ "type": "number" }, { "type": "null" }],
            "description": "The reranker's score for this record, or null if it was not reranked."
          },
          "segments": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/Segment" },
            "description": "The best matching passages in this record."
          },
          "generation": {
            "type": "number",
            "description": "The version of the record's index that produced this result."
          },
          "displayName": {
            "oneOf": [{ "type": "string" }, { "type": "null" }],
            "description": "The record's name, such as a file name or page title, if available."
          }
        }
      },
      "SearchDrops": {
        "type": "object",
        "required": [
          "segmentsBeyondPoolCap",
          "segmentsUnjoinable",
          "segmentsNotSearchable",
          "recordsBeyondTopK"
        ],
        "properties": {
          "segmentsBeyondPoolCap": {
            "type": "integer",
            "description": "Passages left out because the candidate pool was full."
          },
          "segmentsUnjoinable": {
            "type": "integer",
            "description": "Passages left out because they could not be matched to a record."
          },
          "segmentsNotSearchable": {
            "type": "integer",
            "description": "Passages left out because they are not currently searchable."
          },
          "recordsBeyondTopK": {
            "type": "integer",
            "description": "Records left out because they ranked below topK."
          }
        }
      },
      "SearchUsage": {
        "type": "object",
        "required": [
          "returned",
          "segmentsReturned",
          "generation",
          "retrievalMode",
          "rerankOutcome",
          "dropped",
          "permissionFiltered"
        ],
        "properties": {
          "returned": {
            "type": "integer",
            "description": "The number of records returned."
          },
          "segmentsReturned": {
            "type": "integer",
            "description": "The total number of passages returned across all records."
          },
          "generation": {
            "type": "number",
            "description": "The version of the index used for this search."
          },
          "retrievalMode": {
            "type": "string",
            "enum": ["hybrid", "semantic_failed_open", "lexical_failed_open"],
            "description": "How results were retrieved. hybrid combines semantic and keyword search. The other values mean one of the two was unavailable and results came from the other."
          },
          "rerankOutcome": {
            "type": "string",
            "description": "Whether reranking was applied to the results, and if not, why.",
            "enum": [
              "applied",
              "disabled_by_deployment",
              "disabled_by_request",
              "provider_unavailable"
            ]
          },
          "dropped": {
            "$ref": "#/components/schemas/SearchDrops",
            "description": "Counts of matches that were left out of the results."
          },
          "degraded": {
            "type": "string",
            "enum": ["rerank_unavailable", "rewrite_skipped"],
            "description": "Present when part of the search pipeline was skipped, so results may be lower quality than usual."
          },
          "underfilled": {
            "type": "boolean",
            "description": "True if fewer results were returned than requested because there were not enough matches."
          },
          "permissionFiltered": {
            "type": "boolean",
            "description": "True if results were filtered to what the user can access."
          },
          "identities": {
            "type": "object",
            "description": "Which accounts from identity were used to check permissions.",
            "properties": {
              "applied": {
                "type": "object",
                "description": "The accounts that were applied, grouped by source.",
                "additionalProperties": {
                  "type": "array",
                  "items": { "type": "string" }
                }
              },
              "unused": {
                "type": "array",
                "description": "Accounts you passed that did not match any searched source.",
                "items": {
                  "type": "object",
                  "properties": {
                    "source": { "type": "string" },
                    "principal": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      },
      "SearchResponse": {
        "type": "object",
        "required": ["results", "usage"],
        "properties": {
          "results": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/SearchResult" }
          },
          "usage": {
            "$ref": "#/components/schemas/SearchUsage",
            "description": "Details about how the search was run."
          }
        }
      },
      "SegmentContextResponse": {
        "type": "object",
        "required": ["id", "text", "prev", "next", "tokenBudget", "tokenizer"],
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique ID for the record, in the format {syncId}.{recordId}."
          },
          "text": {
            "type": "string",
            "description": "The text around the pointer."
          },
          "prev": {
            "oneOf": [{ "type": "string" }, { "type": "null" }],
            "description": "Pointer to the chunk before this text, or null if this is the start of the record."
          },
          "next": {
            "oneOf": [{ "type": "string" }, { "type": "null" }],
            "description": "Pointer to the chunk after this text, or null if this is the end of the record."
          },
          "tokenBudget": {
            "type": "object",
            "required": ["returnedTokens"],
            "description": "How much text was returned.",
            "properties": {
              "returnedTokens": {
                "type": "integer",
                "description": "The number of tokens in text."
              }
            }
          },
          "tokenizer": {
            "type": "string",
            "enum": ["o200k_base"],
            "description": "The tokenizer used to count tokens."
          }
        }
      },
      "ErrorEnvelope": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": {
            "type": "object",
            "required": ["code", "message", "hint", "retryable", "requestId"],
            "properties": {
              "code": {
                "type": "string",
                "description": "A stable error code you can handle in your code, such as REQUEST_INVALID."
              },
              "message": {
                "type": "string",
                "description": "A human-readable description of what went wrong."
              },
              "hint": {
                "type": "string",
                "description": "Suggested next step to resolve the error."
              },
              "retryable": {
                "type": "boolean",
                "description": "Whether retrying the same request may succeed."
              },
              "retryAfterMs": {
                "type": "integer",
                "description": "How long to wait before retrying, in milliseconds. Only present when retryable is true."
              },
              "requestId": {
                "type": "string",
                "description": "Include this ID when contacting Paragon support about a request."
              },
              "details": {
                "type": "array",
                "description": "Present on validation errors. Lists the fields that failed validation.",
                "items": {
                  "type": "object",
                  "required": ["field", "issue"],
                  "properties": {
                    "field": {
                      "type": "string",
                      "description": "The field that failed validation."
                    },
                    "issue": {
                      "type": "string",
                      "description": "What was wrong with the field."
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "responses": {
      "Error": {
        "description": "The request failed. See the error object for details.",
        "content": {
          "application/json": {
            "schema": { "$ref": "#/components/schemas/ErrorEnvelope" }
          }
        }
      }
    }
  },
  "paths": {
    "/projects/{projectId}/setup-links": {
      "post": {
        "operationId": "createSetupLink",
        "summary": "Create Setup Link",
        "servers": [
          { "url": "https://zeus.useparagon.com", "description": "Production US Cloud" },
          { "url": "https://zeus.eu.paragon.so", "description": "Production EU Cloud" }
        ],
        "security": [{ "apiKeyAuth": [] }, { "bearerAuth": [] }],
        "parameters": [
          {
            "name": "projectId",
            "in": "path",
            "required": true,
            "schema": { "type": "string", "format": "uuid" },
            "description": "Your Paragon Project ID."
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/CreateSetupLinkRequest" },
              "example": {
                "endUserId": "user@example.com",
                "expiresIn": 3600,
                "integrations": ["googledrive", "sharepoint"]
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The Setup Link was created.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/CreateSetupLinkResponse" },
                "example": {
                  "url": "https://<connect-host>/project/6f1c0b2e-1a2b-4c3d-8e9f-0a1b2c3d4e5f/setup?token=eyJhbGciOi...",
                  "expiresAt": "2026-10-14T22:51:00.000Z"
                }
              }
            }
          },
          "400": {
            "description": "The request was invalid. `endUserId` is missing (`56003`), an integration is unknown or not enabled for the project (`56004`), or `expiresIn` is not a positive integer (`56005`).",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SetupLinkError" }
              }
            }
          },
          "401": {
            "description": "The API key or Paragon User Token is missing or invalid."
          },
          "403": {
            "description": "Setup Links are not enabled for the project (`56016`), `endUserId` doesn't match the Paragon User Token (`56014`), or the token's permissions don't allow any of the requested integrations (`56015`).",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SetupLinkError" }
              }
            }
          }
        }
      }
    },
    "/api/context/projects/{projectId}/search": {
      "post": {
        "operationId": "searchContext",
        "summary": "Search Context",
        "parameters": [{ "$ref": "#/components/parameters/ProjectId" }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/SearchRequest" },
              "example": {
                "query": "q2 roadmap",
                "topK": 10,
                "segmentsPerRecord": 1,
                "sources": ["googledrive"],
                "identity": "user@example.com"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The matching records and their best passages.",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/SearchResponse" },
                "example": {
                  "results": [
                    {
                      "id": "6f1c0b2e-1a2b-4c3d-8e9f-0a1b2c3d4e5f.rec_1",
                      "syncId": "6f1c0b2e-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
                      "source": "googledrive",
                      "relevancy": 1,
                      "rerankScore": 0.82,
                      "generation": 3,
                      "displayName": "Q2 roadmap",
                      "segments": [
                        {
                          "pointer": "chk_anchor",
                          "chunkId": "chk_anchor",
                          "text": "The Q2 roadmap covers launch dates.",
                          "relevancy": 1,
                          "rerankScore": 0.82
                        }
                      ]
                    }
                  ],
                  "usage": {
                    "returned": 1,
                    "segmentsReturned": 1,
                    "generation": 3,
                    "retrievalMode": "hybrid",
                    "rerankOutcome": "applied",
                    "dropped": {
                      "segmentsBeyondPoolCap": 0,
                      "segmentsUnjoinable": 0,
                      "segmentsNotSearchable": 0,
                      "recordsBeyondTopK": 0
                    },
                    "permissionFiltered": true,
                    "identities": {
                      "applied": { "googledrive": ["user@example.com"] },
                      "unused": []
                    }
                  }
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "403": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" }
        }
      }
    },
    "/api/context/projects/{projectId}/segments/{pointer}/context": {
      "get": {
        "operationId": "readSegmentContext",
        "summary": "Read Segment Context",
        "parameters": [
          { "$ref": "#/components/parameters/ProjectId" },
          {
            "name": "pointer",
            "in": "path",
            "required": true,
            "schema": { "type": "string" },
            "description": "The pointer from a passage in a search result."
          },
          {
            "name": "direction",
            "in": "query",
            "description": "Which side of the pointer to read: around it, before it, or after it.",
            "schema": {
              "type": "string",
              "enum": ["around", "before", "after"],
              "default": "around"
            }
          },
          {
            "name": "maxTokens",
            "in": "query",
            "description": "The maximum number of tokens to return. At least one chunk is always returned, even if it is larger than this limit.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 32000,
              "default": 2000
            }
          },
          {
            "name": "identity",
            "in": "query",
            "schema": { "type": "string", "maxLength": 1024 },
            "description": "The account whose access applies, used on every source. Unlike search, this endpoint accepts a single string only."
          },
          {
            "name": "email",
            "in": "query",
            "description": "Deprecated. Use identity instead.",
            "schema": {
              "type": "string",
              "maxLength": 1024,
              "deprecated": true
            }
          }
        ],
        "responses": {
          "200": {
            "description": "The text around the pointer.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SegmentContextResponse"
                },
                "example": {
                  "id": "6f1c0b2e-1a2b-4c3d-8e9f-0a1b2c3d4e5f.rec_1",
                  "text": "# Q2 roadmap\nThe Q2 roadmap covers launch dates.",
                  "prev": null,
                  "next": "chk_next",
                  "tokenBudget": { "returnedTokens": 18 },
                  "tokenizer": "o200k_base"
                }
              }
            }
          },
          "400": { "$ref": "#/components/responses/Error" },
          "401": { "$ref": "#/components/responses/Error" },
          "403": { "$ref": "#/components/responses/Error" },
          "404": { "$ref": "#/components/responses/Error" }
        }
      }
    }
  }
}
