Merge branch 'main' into task_t27i1v/find_technical_documentation_with_ai_guide

Author: kodjomiles

.github/workflows/claude-pr-reviewer.yml

@@ -23,7 +23,7 @@ jobs:
 
       - name: Check for changed files
         id: changed-files
-        uses: tj-actions/changed-files@v46
+        uses: tj-actions/changed-files@v47
         with:
           files: |
             docs/**

docs/ai-interfaces/ai-agents/interact-with-ai-agents.md

@@ -153,8 +153,8 @@ const eventSource = new EventSource(apiUrl);
 eventSource.addEventListener('done', (event) => {
   const data = JSON.parse(event.data);
 
-  if (data.quotaUsage) {
-    const { remainingRequests, remainingTokens, remainingTimeMs } = data.quotaUsage;
+  if (data.rateLimitUsage) {
+    const { remainingRequests, remainingTokens, remainingTimeMs } = data.rateLimitUsage;
 
     // Check if quota is running low
     if (remainingRequests < 10 || remainingTokens < 10000) {
@@ -214,11 +214,19 @@ data: Your final answer from the agent.
 
 event: done
 data: {
-  "maxRequests": 200,
-  "remainingRequests": 193,
-  "maxTokens": 200000,
-  "remainingTokens": 179910,
-  "remainingTimeMs": 903
+  "rateLimitUsage": {
+    "maxRequests": 200,
+    "remainingRequests": 193,
+    "maxTokens": 200000,
+    "remainingTokens": 179910,
+    "remainingTimeMs": 903
+  },
+  "monthlyQuotaUsage": {
+    "monthlyLimit": 20,
+    "remainingQuota": 19,
+    "month": "2025-09",
+    "remainingTimeMs": 1766899073
+  }
 }
 ```
 
@@ -283,12 +291,18 @@ Signals that the agent has finished processing and the response stream is comple
 
 ```json showLineNumbers
 {
-  "quotaUsage": {
+  "rateLimitUsage": {
     "maxRequests": 200,
     "remainingRequests": 193,
     "maxTokens": 200000,
     "remainingTokens": 179910,
     "remainingTimeMs": 903
+  },
+  "monthlyQuotaUsage": {
+    "monthlyLimit": 20,
+    "remainingQuota": 19,
+    "month": "2025-09",
+    "remainingTimeMs": 1766899073
   }
 }
 ```
@@ -395,19 +409,40 @@ We limit this data storage strictly to these purposes. You can contact us to opt
 
 ## Limits
 
-Port applies limits to AI agent interactions to ensure fair usage across all customers:
+Port applies two different types of limits to AI agent interactions to ensure fair usage across all customers:
+
+### Rate limits
+- **Query limit**: ~40 queries per hour
+- **Token usage limit**: 800,000 tokens per hour
+- These limits reset hourly
+
+### Monthly quota
+- **Default quota**: 20 AI invocations per month
+- Each invocation of Port AI counts as one request against your quota
+- Quota resets monthly
 
-- **Query limit**: ~40 queries per hour.
-- **Token usage limit**: 800,000 tokens per hour.
 
-You can view your quota limits are available in the API response.
 
 :::caution Usage limits
 Usage limits may change without prior notice. Once a limit is reached, you will need to wait until it resets.  
 If you attempt to interact with an agent after reaching a limit, you will receive an error message indicating that the limit has been exceeded.
 The query limit is estimated and depends on the actual token usage.
 :::
 
+### Monitor your usage
+
+You can monitor your current usage in several ways:
+
+#### Rate limits
+- Check the final `done` event in streaming responses for remaining requests, tokens, and reset time
+
+#### Monthly quota
+You can monitor your current monthly quota usage by making a GET request to the `/v1/quota/ai-invocations` endpoint
+
+:::tip Proactive quota monitoring
+Check your monthly quota before making multiple AI agent requests to avoid hitting limits. When `remainingQuota` is low, consider implementing rate limiting or queuing requests until the monthly quota resets. Note that you may also encounter hourly rate limits, which are separate from this monthly quota.
+:::
+
 ## Common errors
 
 Here are some common errors you might encounter when working with AI agents and how to resolve them:
@@ -513,7 +548,38 @@ Port applies the following limits to AI agent interactions:
 - **Query limit**: ~40 queries per hour
 - **Token usage limit**: 800,000 tokens per hour
 
-You can monitor your current usage in the final `done` event showing your remaining requests, tokens, and reset time.
+You can monitor your current usage in several ways:
+- Check the final `done` event in streaming responses for remaining requests, tokens, and reset time (hourly rate limits)
+- Make a GET request to `/v1/quota/ai-invocations` to see your monthly quota status
+
+Note that Port has both hourly rate limits and monthly quotas. For detailed information, see the [Limits](#limits) section above.
+
+</details>
+
+<details>
+<summary><b>What happens when I reach a limit and what can I do? (Click to expand)</b></summary>
+
+**What happens when you reach a limit:**
+- You are temporarily blocked from making new AI agent requests
+- You will receive an error message indicating which limit has been exceeded
+- Access resumes automatically when the limit resets
+
+**What you can do:**
+
+**For rate limits (hourly):**
+- Wait for the limits to reset (they reset every hour)
+- Monitor the `remainingTimeMs` field to know exactly when you can make requests again
+- The error message will indicate it's a rate limit issue
+
+**For monthly quota:**
+- Wait for the monthly quota to reset at the beginning of the next month
+- Contact our support team to learn more about our plans and quota upgrades available for your organization
+- The error message will indicate it's a quota limit issue
+
+**General recommendations:**
+- Implement rate limiting in your applications to avoid hitting limits
+- Monitor your usage proactively using the monitoring methods described above
+- Consider batching requests or optimizing your AI agent interactions for efficiency
 
 </details>
 

docs/api-reference/approve-an-action-run.api.mdx

@@ -1,11 +1,11 @@
 ---
 id: approve-an-action-run
 title: "Approve an action run"
-description: "This route allows you to approve or decline a request to execute an action that requires approval.<br/><br/>To learn more about manual approval for actions, check out the [documentation](https://docs.port.io/create-self-service-experiences/set-self-service-actions-rbac/#configure-manual-approval-for-actions)."
+description: "This route allows you to approve or decline a request to execute an"
 sidebar_label: "Approve an action run"
 hide_title: true
 hide_table_of_contents: true
-api: eJztWNtu4zYQ/RWCfWgCxNEm3SejKOBcgAab7hputkARGAEtjW1uJFElKSdew//eGZK6OJadS1+yQPPgSCJneOZwOBeuuBUzw/u3fBBbqXI2KnPDx0c8ARNrWdA33uc3c2mYVqUFJtJUPRi2VCWziomi0GoBTGmWQJzKHCcwDf+UYCyNwyPETipnwi9g58K6GVKDCfIiPf51oqPf3M+NYikInbNMaRSc4KosE3kp0no2m+J6Xp85YvEc4ntG0+wc2G2i4jKD3AoaHh/MrS1MP4rwszkulLbHUkWxBmGhZyCd4o9eyBh68FiAlpDHYCIDdnMwLNbTExFHP8Uqn8pZqaHngfUqYD0EVs09POZHPFBxppIl7684ClqERo8oksrYgYy+GWJ5xQ2akgl6sssCkHc1+QaxRT2oHtFZCcbNQ+NK05pnrJb5DOdBXma0mxeX59dXny/xy2A4HH3565KP1082dVt4c88HrPWOG5hESDryhlgd/0T2TC4gZx7OMV/jEiJJJAmIdNiCPBWpAc8GbntCCIMN4zVJNQNWl4AfCqFFBhY0+WYHMVsGL07wZXHqzJQEH3nXS/yWox58XaAqsqu9lkO1PtqtvtJVCDtvVOkyv5MJf4p6+8wAkwnutpxK0ExNHWPhFKAO5AvPmcHzoaVdOjMn6Peg8XFMQ3g+CvQjv+WnH07o3+YSXz4hihf71KYPqXv6DfQRfmIOYT3vfWh7F1OTtIQCX+xLNFS0dGqy0qbQjNw2u52Xaeq3OG67cNeMBFL0nzbUiVIYWHK+6XC3bTQkSC92+YMb4d3sBzdiE+qmISQpHob7Z0CeQDKwXXEDI1gmcIQnlAisxJONAkaVOu42OGgdtyAPQtRvz69MawS67dgdyQbX1xS2P/9NsXGTHydCCHYlgHroWkwg3b8tmKzv2zOE1oICZpiJuKWFrGsRWqXMMqGXnQhEBy21+/nln3KyNzGhyhLz8FWy3x4yvINYl18KsUyVSF6BqHuXCIpO9/oTRnNHwgw2ImHt8gh0mcdzrXL5vftQHHHMfHPVHWXnIBKXFZ872aOvn++uLnbwMQn1yH4VVC3dufTy+IKgjrnjqguz/2vSWecuVs7XHJrK+UjUl2vJWbe/yQxRYLbbM6Uskj2jQf1rAkVQ+HKRrUjH6yC9QWRHdKnDUn3utwIDJvPxM7XXVuXgd+VjV11xAVNRppaNqi37j1UGChtb11sctFbd+SYDY/DkdMecJwZXevYbXln5cdvKAVaznln2IO3clWdEOWahpF25PQjDcmWx6C3z5F1T0Ui9zhvexkSg9uSXbWpHoQOkOMOwdbQKmzqhZ8AOUplJS99O/pBnh++azteR+HKbA3Gnp9vEUdNAljf0Jwo86RhSYr81rhH/2bBAzXum8K0e+RYeQp6pkid1bTG1ba576/NocRKF1jzCXGWilW/k1pFoRVrs96um02V6Xt0fiEJW1wecesbt0dI0E1qd3Z+EzhNe9Xc1gSj2CVpd6qBE7Fp+FyExuO7Tp3zHMlEyaq4ULh9FVvgCvaoIW53/JqPtlnaqHAZf3PMhgmaD4RU10KFL7vOT4w80t1DGZsJ5UQUx3Pg0NzrUNG7dLdQu+f/d0VvvjoKPUPUVFamQeav89D4drj2CEHf9O/3r11cUtWujQ84VnfNbvlpNhIGvOl2v6bO/KCGHT6QRk7S+GTni9+ib7asTVFQSJOffC6ElTe8W3ekOB6MQKQ7Z8zckO0ioTk++bIOq8Abj1+O6XHYQ/eC5B9K7IRWN8FbYpCPuJQZxDIXdO3fcijrDwc3577wpsTOVuEsj8cBdy+qRqsJvGdXN9G3FU5HPShdeuVfqbtNK2uZ2uLh34SI8kFmdXDyNI94S+iW7OkVWKx+M0CnqjXdDOyUCt9Vs2hq6zfsXimjDMQ==
+api: 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
 sidebar_class_name: "patch api-method"
 info_path: api-reference/port-api
 custom_edit_url: null
@@ -36,7 +36,14 @@ import Heading from "@theme/Heading";
 
 
 
-This route allows you to approve or decline a request to execute an action that requires approval.<br/><br/>To learn more about manual approval for actions, check out the [documentation](https://docs.port.io/create-self-service-experiences/set-self-service-actions-rbac/#configure-manual-approval-for-actions).
+This route allows you to approve or decline a request to execute an
+action that requires approval.<br/><br/>To learn more about manual
+approval for actions, check out the
+[documentation](https://docs.port.io/create-self-service-experiences/set-self-service-actions-rbac/#configure-manual-approval-for-actions).
+:::info Version parameter value
+Set the `version` parameter to `v2` for the latest version of the API.
+:::
+
 
 <Heading
   id={"request"}
@@ -47,7 +54,7 @@ This route allows you to approve or decline a request to execute an action that
 </Heading>
 
 <ParamsDetails
-  parameters={[{"schema":{"type":"string","enum":["v1","v2"]},"in":"query","name":"version","required":false},{"schema":{"type":"string"},"in":"path","name":"run_id","required":true,"description":"The identifier of the action run."}]}
+  parameters={[{"schema":{"type":"string","enum":["v1","v2"]},"in":"query","name":"version","required":false,"description":"Specifies the API version to use. Please use `v2` for the latest version of the API."},{"schema":{"type":"string"},"in":"path","name":"run_id","required":true,"description":"The identifier of the action run."}]}
 >
 
 </ParamsDetails>