{"info":{"title":"Amp External API","version":"v2","description":"The Amp External API allows integrations to interact with Amp workspace data. Currently, this API is only available to Amp Enterprise customers upon request.\n\nAll data access is scoped to the Amp workspace that owns the provided client credentials. Each endpoint verifies the client has the prerequisite OAuth2 scopes for that particular endpoint.\n\nFor integrations and automations using the Amp product itself, use the Amp CLI or SDK instead."},"openapi":"3.0.0","tags":[{"name":"Threads","description":"APIs for working with Amp threads."},{"name":"Workspace","description":"APIs for working with the Amp workspace."}],"servers":[{"url":"https://ampcode.com"}],"security":[{"v2.OAuth2AppAuth":[]}],"components":{"securitySchemes":{"v2.OAuth2AppAuth":{"type":"oauth2","name":"Amp M2M OAuth2 App","flows":{"clientCredentials":{"scopes":{"amp.api:workspace.threads.meta:view":"View basic thread metadata for all threads using the Amp external API","amp.api:workspace.threads.contents:view":"View contents and advanced details of all threads using the Amp external API","amp.api:workspace.threads:manage":"Manage threads using the Amp external API","amp.api:workspace.analytics:view":"View all workspace analytics using the Amp external API","amp.api:workspace.members:view":"View workspace members and member information using the Amp external API"},"tokenUrl":"https://auth.ampcode.com/oauth2/token"}}}},"schemas":{},"parameters":{}},"paths":{"/api/v2/threads":{"get":{"description":"List all threads from your workspace, including private and group-shared threads, with optional filtering and pagination. Threads are listed by time of first sync in ascending order for sorting stability.","operationId":"v2_threads_list","tags":["Threads"],"security":[{"v2.OAuth2AppAuth":["amp.api:workspace.threads.meta:view"]}],"parameters":[{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Maximum number of results to return."},"required":false,"description":"Maximum number of results to return.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor for pagination to get the next set of results."},"required":false,"description":"Cursor for pagination to get the next set of results.","name":"cursor","in":"query"},{"schema":{"type":"string","description":"Search query to filter threads by content."},"required":false,"description":"Search query to filter threads by content.","name":"query","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Only include threads where the thread's initial sync time is after this date (ISO 8601 format)."},"required":false,"description":"Only include threads where the thread's initial sync time is after this date (ISO 8601 format).","name":"after","in":"query"},{"schema":{"type":"string","format":"date-time","description":"Only include threads where the thread's initial sync time is before this date (ISO 8601 format)."},"required":false,"description":"Only include threads where the thread's initial sync time is before this date (ISO 8601 format).","name":"before","in":"query"},{"schema":{"type":"string","enum":["ASC","DESC"],"description":"Sort order for results. ASC = oldest first (default), DESC = newest first."},"required":false,"description":"Sort order for results. ASC = oldest first (default), DESC = newest first.","name":"sort","in":"query"},{"schema":{"type":"string","format":"email","description":"Only include threads created by the user with this email address. The user must be in the workspace."},"required":false,"description":"Only include threads created by the user with this email address. The user must be in the workspace.","name":"userEmail","in":"query"},{"schema":{"type":"string","description":"Only include threads created by the user with this user ID. The user must be in the workspace."},"required":false,"description":"Only include threads created by the user with this user ID. The user must be in the workspace.","name":"userID","in":"query"}],"responses":{"200":{"description":"The request has succeeded.","content":{"application/json":{"schema":{"type":"object","properties":{"nextCursor":{"type":"string","description":"Pagination cursor for getting the next set of results."},"threads":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string","description":"Unique identifier for the thread."},"title":{"type":"string","description":"Title of the thread. Only returned if the client has the 'amp.api:workspace.threads.contents:view' scope."},"createdAt":{"type":"string","format":"date-time","description":"When the thread was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the thread was last updated."},"firstSyncedAt":{"type":"string","format":"date-time","description":"When the thread was first synced."},"creatorUserID":{"type":"string","description":"User ID of the thread creator."},"mainThreadID":{"type":"string","description":"ID of the main thread, if this is a sub-thread"},"repositories":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string","description":"The normalized URL to the repository (e.g., https://github.com/owner/repo). Normalization is not guaranteed (e.g., for obscure or ambiguous SSH Git remote URL formats), so you should inspect for outliers."},"dir":{"type":"string","description":"The subdirectory within the repository in which the thread started working. Omitted if it is the root directory of the repository."}},"required":["url"]},"description":"Repositories in which this thread started working. Only returned if the client has the 'amp.api:workspace.threads.contents:view' scope."},"subThreads":{"type":"array","items":{}}},"required":["id","creatorUserID"]},"description":"Array of threads matching the query"}},"required":["threads"]}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"]}}}},"403":{"description":"Forbidden: missing client scope(s)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"]}}}}}}},"/api/v2/threads/{threadID}":{"delete":{"description":"Delete a thread by ID.","operationId":"v2_threads_delete","tags":["Threads"],"security":[{"v2.OAuth2AppAuth":["amp.api:workspace.threads:manage"]}],"parameters":[{"schema":{"type":"string","description":"ID of the target thread, with the format \"T-...\"."},"required":true,"description":"ID of the target thread, with the format \"T-...\".","name":"threadID","in":"path"},{"schema":{"type":"string"},"required":true,"name":"Content-Type","in":"header"}],"responses":{"204":{"description":"Thread successfully deleted"},"400":{"description":"Invalid thread ID parameter","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"]}}}},"401":{"description":"Unauthorized - authentication required","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"]}}}},"403":{"description":"Forbidden: missing client scope(s)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"]}}}}}}},"/api/v2/threads/{threadID}/messages":{"get":{"description":"Get the messages belonging to a thread.","operationId":"v2_threads_messages_list","tags":["Threads"],"security":[{"v2.OAuth2AppAuth":["amp.api:workspace.threads.contents:view"]}],"parameters":[{"schema":{"type":"string","description":"ID of the target thread, with the format \"T-...\"."},"required":true,"description":"ID of the target thread, with the format \"T-...\".","name":"threadID","in":"path"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":50,"description":"Maximum number of results to return."},"required":false,"description":"Maximum number of results to return.","name":"limit","in":"query"},{"schema":{"type":"string","description":"Cursor for pagination to get the next set of results."},"required":false,"description":"Cursor for pagination to get the next set of results.","name":"cursor","in":"query"}],"responses":{"200":{"description":"The request has succeeded.","content":{"application/json":{"schema":{"type":"object","properties":{"nextCursor":{"type":"string","description":"Pagination cursor for getting the next set of results."},"messages":{"type":"array","items":{},"description":"Array of message objects in the thread. Message shapes are currently not stable and may change at any time. For scanning purposes, we recommend checking the entire content of each message."}},"required":["messages"]}}}},"400":{"description":"Invalid thread ID or query parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"]}}}},"403":{"description":"Forbidden: missing client scope(s)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"]}}}},"404":{"description":"Thread not found","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"]}}}}}}},"/api/v2/threads/{threadID}/usage":{"get":{"description":"Get usage information for a thread. Thread usage data is only available for threads less than 90 days old.","operationId":"v2_threads_usage_get","tags":["Threads"],"security":[{"v2.OAuth2AppAuth":["amp.api:workspace.threads.meta:view"]}],"parameters":[{"schema":{"type":"string","description":"ID of the target thread, with the format \"T-...\"."},"required":true,"description":"ID of the target thread, with the format \"T-...\".","name":"threadID","in":"path"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"threadID":{"type":"string","description":"The thread ID"},"subThreadIDs":{"type":"array","items":{"type":"string"},"description":"IDs of sub-threads included in the usage calculation"},"usage":{"type":"number","description":"Total thread cost in USD"}},"required":["threadID","subThreadIDs","usage"]}}}},"400":{"description":"Invalid thread ID parameter","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"]}}}},"403":{"description":"Forbidden: missing client scope(s)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"]}}}},"404":{"description":"Thread not found or usage data not available","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"]}}}}}}},"/api/v2/workspace/members":{"get":{"description":"List all members in the workspace.","operationId":"v2_workspace_members_list","tags":["Workspace"],"security":[{"v2.OAuth2AppAuth":["amp.api:workspace.members:view"]}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"members":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Full name of the user"},"email":{"type":"string","format":"email","description":"The primary email address of the user"},"role":{"type":"string","enum":["admin","member"],"description":"Role of the user in the workspace"}},"required":["name","email","role"]},"description":"All members of the workspace"}},"required":["members"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"]}}}},"403":{"description":"Forbidden: missing client scope(s)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"]}}}}}}},"/api/v2/workspace/analytics/daily-usage":{"get":{"description":"Get daily usage analytics for your workspace. Returns usage metrics and costs for users in the specified time period.","operationId":"v2_workspace_analytics_daily_usage","tags":["Workspace"],"security":[{"v2.OAuth2AppAuth":["amp.api:workspace.analytics:view"]}],"parameters":[{"schema":{"type":"string","format":"date","description":"End date (YYYY-MM-DD). Default: today"},"required":false,"description":"End date (YYYY-MM-DD). Default: today","name":"endDate","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":365,"default":1,"description":"Number of days to include."},"required":false,"description":"Number of days to include.","name":"lookbackDays","in":"query"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"metadata":{"type":"object","properties":{"startDate":{"type":"string","format":"date","description":"Start date of the period"},"endDate":{"type":"string","format":"date","description":"End date of the period"},"activeUsers":{"type":"number","description":"Users with non-zero usage in the period"},"totalUsers":{"type":"number","description":"Total users in the workspace"},"totalUsage":{"type":"number","description":"Total usage in the period (USD)"}},"required":["startDate","endDate","activeUsers","totalUsers","totalUsage"],"description":"Metadata about the usage period"},"data":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date","description":"Date in YYYY-MM-DD format"},"users":{"type":"array","items":{"type":"object","properties":{"user":{"type":"object","properties":{"id":{"type":"string","description":"User ID"},"email":{"type":"string","format":"email","description":"User email - only returned if the client has the \"amp.api:workspace.members:view\" scope"}},"required":["id"],"description":"User information"},"metrics":{"type":"object","properties":{"linesAdded":{"type":"number","description":"Lines added by the user"},"linesDeleted":{"type":"number","description":"Lines deleted by the user"},"linesModified":{"type":"number","description":"Lines modified by the user"},"usage":{"type":"number","description":"Usage for the user (USD)"}},"required":["linesAdded","linesDeleted","linesModified","usage"],"description":"Usage metrics for the user"},"models":{"type":"object","additionalProperties":{"type":"object","properties":{"requests":{"type":"number","description":"Number of requests for the model"},"inputTokens":{"type":"number","description":"Total uncached input tokens consumed by the model for this user/day"},"outputTokens":{"type":"number","description":"Total output tokens consumed by the model for this user/day"},"cacheReadInputTokens":{"type":"number","description":"Total cache-read input tokens consumed by the model for this user/day"},"cacheCreationInputTokens":{"type":"number","description":"Total cache-creation input tokens consumed by the model for this user/day"},"totalTokens":{"type":"number","description":"Total tokens consumed by the model for this user/day"}},"required":["requests","inputTokens","outputTokens","cacheReadInputTokens","cacheCreationInputTokens","totalTokens"],"description":"Request and token metrics for a model"},"description":"Per-model request and token counts for the user"}},"required":["user","metrics","models"]},"description":"Usage data for all users on this day"}},"required":["date","users"]},"description":"Daily usage data for each day in the period"}},"required":["metadata","data"]}}}},"400":{"description":"Invalid query parameters","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"]}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"]}}}},"403":{"description":"Forbidden: missing client scope(s)","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"]}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","description":"Error message describing what went wrong"}},"required":["error"]}}}}}}}},"webhooks":{}}