@widgetic/api-contracts 1.11.106 → 1.11.109
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +1 -1
- package/metadata.json +5 -5
- package/openapi-public.json +658 -37
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -4,7 +4,7 @@ What the Widgetic API and the Widgetic MCP server accept, as data. This package
|
|
|
4
4
|
|
|
5
5
|
| File | What it is |
|
|
6
6
|
|---|---|
|
|
7
|
-
| `openapi-public.json` | The public OpenAPI description of the Widgetic REST API: the
|
|
7
|
+
| `openapi-public.json` | The public OpenAPI description of the Widgetic REST API: the 161 operations a customer or a partner can call with an API key. |
|
|
8
8
|
| `mcp-tools.json` | The Widgetic MCP tool contract, version 1.12.0: the 32 tools that `tools/list` serves, with their input and output schemas, annotations and scopes. |
|
|
9
9
|
| `metadata.json` | Where the two files came from: the commit of the Widgetic API gateway, the SHA-256 of each file and the counts. |
|
|
10
10
|
|
package/metadata.json
CHANGED
|
@@ -1,18 +1,18 @@
|
|
|
1
1
|
{
|
|
2
2
|
"package": "@widgetic/api-contracts",
|
|
3
|
-
"version": "1.11.
|
|
3
|
+
"version": "1.11.109",
|
|
4
4
|
"publishTag": "latest",
|
|
5
5
|
"source": {
|
|
6
|
-
"commit": "
|
|
6
|
+
"commit": "21238b5bbb97b100ef2edb0d9d98d167467e8d18",
|
|
7
7
|
"branch": null,
|
|
8
8
|
"dirty": false,
|
|
9
9
|
"atOriginMain": true
|
|
10
10
|
},
|
|
11
11
|
"openApi": {
|
|
12
12
|
"file": "openapi-public.json",
|
|
13
|
-
"sha256": "
|
|
14
|
-
"paths":
|
|
15
|
-
"operations":
|
|
13
|
+
"sha256": "750e774e958a819377963d0a6f7a2feb2e7b70327b614053fdbe748e3e5e5865",
|
|
14
|
+
"paths": 120,
|
|
15
|
+
"operations": 161,
|
|
16
16
|
"servers": [
|
|
17
17
|
"https://api.widgetic.com/v1"
|
|
18
18
|
]
|
package/openapi-public.json
CHANGED
|
@@ -402,7 +402,7 @@
|
|
|
402
402
|
"post": {
|
|
403
403
|
"operationId": "reportPublicWorkflowEvents",
|
|
404
404
|
"summary": "Report what visitors did in a Workflow, as counts",
|
|
405
|
-
"description": "Public report of counts for a workflow, sent by the embed. No API key. Each event is one id and a number: a visitor reached a block (`n`), took a connection (`e`), or could not be moved on (`f`). Nothing else is kept: no visitor, no value a visitor typed, no address. A batch carries at most 100 events and 16 KB.\nA report is accepted only with the `token` the workflow's own read handed out for that `versionId`, so a page that never read the workflow cannot raise its numbers. An expired token (`EVENT_TOKEN_EXPIRED`) is refused with 401: read the workflow again for a new one. Counts for ids that are not in that version, or for a workflow that is not live, are not recorded and the answer says so (`recorded: false`) with 200: the visitor's page has nothing to fix.\nThe body is JSON, sent as `application/json` or as `text/plain` (a \"simple\" cross-origin request, which is what lets a report leave a page that is being closed).\n**Address.** `https://api.widgetic.com/embed/workflows/{workflowId}/events`: the root of the API host, NOT under `/v1`. A client generated from this description for `https://api.widgetic.com/v1` must be given the base address `https://api.widgetic.com` for the calls of the `Public Embed` tag.",
|
|
405
|
+
"description": "Public report of counts for a workflow, sent by the embed. No API key. Each event is one id and a number: a visitor reached a block (`n`), took a connection (`e`), or could not be moved on (`f`). Nothing else is kept: no visitor, no value a visitor typed, no address. A batch carries at most 100 events and 16 KB. The same report may carry `heights`: how tall a step settled at in the browser, which the embed code of the workflow uses to start its box at a real height (a composition, a whole number of pixels, nothing about the visitor).\nA report is accepted only with the `token` the workflow's own read handed out for that `versionId`, so a page that never read the workflow cannot raise its numbers. An expired token (`EVENT_TOKEN_EXPIRED`) is refused with 401: read the workflow again for a new one. Counts for ids that are not in that version, or for a workflow that is not live, are not recorded and the answer says so (`recorded: false`) with 200: the visitor's page has nothing to fix.\nThe body is JSON, sent as `application/json` or as `text/plain` (a \"simple\" cross-origin request, which is what lets a report leave a page that is being closed).\n**Address.** `https://api.widgetic.com/embed/workflows/{workflowId}/events`: the root of the API host, NOT under `/v1`. A client generated from this description for `https://api.widgetic.com/v1` must be given the base address `https://api.widgetic.com` for the calls of the `Public Embed` tag.",
|
|
406
406
|
"tags": [
|
|
407
407
|
"Partner",
|
|
408
408
|
"Public Embed"
|
|
@@ -438,7 +438,7 @@
|
|
|
438
438
|
},
|
|
439
439
|
"responses": {
|
|
440
440
|
"200": {
|
|
441
|
-
"description": "Nothing was counted (`recorded` is false, with the reason)",
|
|
441
|
+
"description": "Nothing was counted or kept (`recorded` is false, with the reason)",
|
|
442
442
|
"content": {
|
|
443
443
|
"application/json": {
|
|
444
444
|
"schema": {
|
|
@@ -10546,7 +10546,7 @@
|
|
|
10546
10546
|
"post": {
|
|
10547
10547
|
"operationId": "createManagedUserEditorSession",
|
|
10548
10548
|
"summary": "Create an editor session for a managed user",
|
|
10549
|
-
"description": "Makes a short-lived credential that lets the browser of ONE of your managed users use Widgetic's editor\npieces, such as the File Browser and the composition editor, without your API key ever reaching that\nbrowser. Call this from your server when the page that hosts the editor opens, and hand the `token` in\nthe answer to that page.\n\nThe token is shown once. It starts with `wgt_ses_` and the browser sends it as\n`Authorization: Bearer <token>`. It can do only what the `surfaces` you name allow, and only for this\nmanaged user:\n\n- `files`: upload a file (`uploadsPost`) and list the files uploaded for this user (`uploadsGet`). Every\n file is filed for this user and stored in your own storage destination, never in Widgetic's: a file a\n customer uploads is yours to keep, and takes none of your storage allowance. Partner storage is not\n optional, so no session, whatever its surfaces, can be made until you have set a destination\n (`setPartnerStorageDestination`); until then it is refused with 409 and `PARTNER_STORAGE_REQUIRED`, and\n when the destination cannot be used with 503 and `STORAGE_DESTINATION_UNAVAILABLE`. A destination you\n remove after the session was made stops its uploads too (the same 409; the browser is only told that\n the feature is not available right now). To keep a customer from uploading, leave `files` out of the\n session and hand the editors your own media library instead (`mediaLibrary`).\n- `editor`: edit one of this user's compositions: read it (`getCompositionById`, its content, design,\n embed settings and schemas), check a content change (`validateCompositionContent`), and change its\n name, content, design and embed settings (`updateComposition`, `setDynamicContent`). It can reach\n only compositions you created for this managed user (tag them with `managedUserId` when you create\n them); any other composition, including another of your users', answers 404.\n- `creator`: use Widgetic's widget creator for this user, including its AI. Draw on canvases and save\n them (`getAllCanvases`, `getCanvas`, `createCanvas`, `updateCanvas`, `previewDeleteCanvas`,\n `deleteCanvas`); make, change, copy and delete the widgets on them (`createWidget`, `getWidgets`,\n `getWidgetsBatch`, `updateWidget`, `uploadWidgetThumbnail`, `duplicateWidget`, `deleteWidget`);\n list and make the compositions of a widget it built (`getAllCompositions`, `createComposition`), which\n is how it shows the widget with sample values; keep the\n conversation of each widget (`getConversationsByWidgetId`, `createConversationForWidget`,\n `updateConversation`, `getMessages`, `createMessage`, `updateMessage`, `restoreCheckpoint`); and read a\n widget's schemas and give it its repository (`getWidgetContentSchema`, `getWidgetDesignSchema`,\n `updateWidgetRepository`). The AI that builds a widget is part of it: list the models\n (`agentModelsGet`), open the widget's repository (`agentRepositoriesPost`,\n `agentRepositoriesRepoIdGet`), start a generation and follow or cancel it (`agentCodeGeneratePost`,\n `operationsStreamGet`, `operationsIdGet`, `operationsIdCancelPost`), build and preview the result\n (`agentWidgetBuilderRepoHeadWidgetIdGet`, `buildWidgetFromRepo`, `previewWidgetVersion`), publish a\n version of the widget and move between its versions (`agentWidgetBuilderPublishWidgetIdPost`,\n `getWidgetPublishHistory`, `setWidgetPublishHistoryLive`, `renameWidgetPublishHistoryTitle`), and\n turn a stroke or a sentence into a decision (`agentShapeRecognizePost`, `agentDesignResolvePost`). It can\n also offer the customer your presets as starting points: read them and ask for a copy for this customer\n (`listMyPresets`, `copyMyPreset`; you choose the presets with `setPartnerPreset`).\n What the session makes is filed for this managed user, and the lists it reads hold only this user's\n canvases, widgets and compositions. It can reach only canvases, widgets, compositions, repositories,\n uploaded files and operations made for this managed user (tag the canvases and widgets you create\n with `managedUserId`); any other canvas, widget, composition, conversation, message, repository, file\n or operation, including another of your users', answers 404. The creator also saves the composition\n it is editing (`updateComposition`, from the `editor` surface) and attaches pictures to its chat\n (`uploadsPost`, from the `files` surface), and the surfaces do not imply one another: to open the\n whole creator for a user, ask for `creator`, `editor` and `files` together. A generation or a build\n one user starts can be followed and cancelled by that user and by you, never by another of your\n users. The AI is paid for by your account, as your own calls are: its credits and allowances are\n yours. A session cannot make a widget public (publishing a version does not), file one under a\n project or an organization, or set anything the creator does not set: a body with another field is\n refused with 403 and `EDITOR_SESSION_FIELD_NOT_ALLOWED`.\n- `workflows`: use Widgetic's Workflows editor for this user. List their workflows and the compositions\n a workflow of theirs can chain (`listWorkspaceWorkflows`, `listWorkspaceWorkflowCompositionOptions`);\n list the starting points you offer them and make a workflow from one, which gives the user their own copy\n of every widget it chains, a composition of their own on each copy, and a draft\n (`listWorkspaceWorkflowPresets`, `createWorkspaceWorkflowFromPreset`; you offer them with\n `setPartnerWorkflowPreset`);\n make, open, change and delete one (`createWorkspaceWorkflow`, `getWorkspaceWorkflow`,\n `saveWorkspaceWorkflow`, `deleteWorkspaceWorkflow`) and copy it (`duplicateWorkspaceWorkflow`); publish\n it or discard the changes of its draft (`publishWorkspaceWorkflow`,\n `discardWorkspaceWorkflowChanges`); read and restore its versions (`listWorkspaceWorkflowVersions`,\n `getWorkspaceWorkflowVersion`, `restoreWorkspaceWorkflowVersion`); pause, resume, archive and unarchive it\n (`pauseWorkspaceWorkflow`, `resumeWorkspaceWorkflow`, `archiveWorkspaceWorkflow`,\n `unarchiveWorkspaceWorkflow`); and read its counts (`getWorkspaceWorkflowStats`). The workspace in each\n path is `personal`: a session has no other, and a path that names an organization is refused. What the\n session makes is filed for this managed user (`managedUserId`), the lists hold only this user's workflows,\n and it can reach only workflows made for this managed user; any other workflow, including one of yours\n or of another of your users, answers 404. A workflow can chain only the compositions you made for this\n managed user (tag them with `managedUserId`): one that belongs to anybody else is not available, and\n publishing a workflow that uses it is refused. A customer can have at most 50 workflows, and what a\n customer's session reads never says who published a version. A session cannot set who a workflow belongs\n to or which workspace it is in: a body with another field is refused with 403 and\n `EDITOR_SESSION_FIELD_NOT_ALLOWED`.\n\nEverything else is refused with 403 and `EDITOR_SESSION_ROUTE_NOT_ALLOWED`: a session cannot read your\naccount, make more sessions, change your presets or delete a composition, and a session without the `creator` surface cannot\ncreate or list compositions. Create the composition yourself with your API key, then open the editor on it.\n\nA session ends at `expiresAt` (at most four hours), when you end it (`revokeManagedUserEditorSession`),\nor when the managed user is switched off or deleted. A managed user can have at most 100 live sessions at\nonce (`429 EDITOR_SESSION_LIMIT_REACHED`). A session that is bound to a web page (`allowedOrigin`) is\nrefused from any other origin.\n\nThe AI the session runs is paid for with your credits. Set `maxCredits` to hold the session to a number\nof them: once its generations have taken that many (a generation that fails is refunded and does not\ncount), the next one is refused with 402 and `EDITOR_SESSION_CREDIT_LIMIT_REACHED`, and the browser is told\nonly that the feature is not available right now. Without it, the limit Widgetic has set for your account\napplies when it has set one (the same limit for every session you make, and `maxCredits: null` asks for\nnone), and otherwise the credits of your account are the only ceiling. What each of your users' sessions\nhas spent is in `getManagedUserUsage`.\n\nEach call makes a new session. It does not take an `Idempotency-Key`: the answer holds the token, and\nthe token is never stored where a retry could read it back. The answer is sent with\n`Cache-Control: no-store`.\n",
|
|
10549
|
+
"description": "Makes a short-lived credential that lets the browser of ONE of your managed users use Widgetic's editor\npieces, such as the File Browser and the composition editor, without your API key ever reaching that\nbrowser. Call this from your server when the page that hosts the editor opens, and hand the `token` in\nthe answer to that page.\n\nThe token is shown once. It starts with `wgt_ses_` and the browser sends it as\n`Authorization: Bearer <token>`. It can do only what the `surfaces` you name allow, and only for this\nmanaged user:\n\n- `files`: upload a file (`uploadsPost`) and list the files uploaded for this user (`uploadsGet`). Every\n file is filed for this user and stored in your own storage destination, never in Widgetic's: a file a\n customer uploads is yours to keep, and takes none of your storage allowance. Partner storage is not\n optional, so no session, whatever its surfaces, can be made until you have set a destination\n (`setPartnerStorageDestination`); until then it is refused with 409 and `PARTNER_STORAGE_REQUIRED`, and\n when the destination cannot be used with 503 and `STORAGE_DESTINATION_UNAVAILABLE`. A destination you\n remove after the session was made stops its uploads too (the same 409; the browser is only told that\n the feature is not available right now). To keep a customer from uploading, leave `files` out of the\n session and hand the editors your own media library instead (`mediaLibrary`).\n- `editor`: edit one of this user's compositions: read it (`getCompositionById`, its content, design,\n embed settings and schemas), check a content change (`validateCompositionContent`), and change its\n name, content, design and embed settings (`updateComposition`, `setDynamicContent`). For a widget that\n answers visitors' questions from documents (the `ai-answers` adapter), it also lists those documents,\n adds one as text or as a file (a text file or a picture; a PDF once PDFs are read), and removes one\n (`getAiAnswersKnowledge`, `addAiAnswersKnowledgeDocument`, `addAiAnswersKnowledgeFile`,\n `removeAiAnswersKnowledgeDocument`); adding costs no credits, and is limited for each of your users\n separately. It can reach\n only compositions you created for this managed user (tag them with `managedUserId` when you create\n them); any other composition, including another of your users', answers 404.\n- `creator`: use Widgetic's widget creator for this user, including its AI. Draw on canvases and save\n them (`getAllCanvases`, `getCanvas`, `createCanvas`, `updateCanvas`, `previewDeleteCanvas`,\n `deleteCanvas`); make, change, copy and delete the widgets on them (`createWidget`, `getWidgets`,\n `getWidgetsBatch`, `updateWidget`, `uploadWidgetThumbnail`, `duplicateWidget`, `deleteWidget`);\n list and make the compositions of a widget it built (`getAllCompositions`, `createComposition`), which\n is how it shows the widget with sample values; keep the\n conversation of each widget (`getConversationsByWidgetId`, `createConversationForWidget`,\n `updateConversation`, `getMessages`, `createMessage`, `updateMessage`, `restoreCheckpoint`); and read a\n widget's schemas and give it its repository (`getWidgetContentSchema`, `getWidgetDesignSchema`,\n `updateWidgetRepository`). The AI that builds a widget is part of it: list the models\n (`agentModelsGet`), open the widget's repository (`agentRepositoriesPost`,\n `agentRepositoriesRepoIdGet`), start a generation and follow or cancel it (`agentCodeGeneratePost`,\n `operationsStreamGet`, `operationsIdGet`, `operationsIdCancelPost`), build and preview the result\n (`agentWidgetBuilderRepoHeadWidgetIdGet`, `buildWidgetFromRepo`, `previewWidgetVersion`), publish a\n version of the widget and move between its versions (`agentWidgetBuilderPublishWidgetIdPost`,\n `getWidgetPublishHistory`, `setWidgetPublishHistoryLive`, `renameWidgetPublishHistoryTitle`), and\n turn a stroke or a sentence into a decision (`agentShapeRecognizePost`, `agentDesignResolvePost`). It can\n also offer the customer your presets as starting points: read them and ask for a copy for this customer\n (`listMyPresets`, `copyMyPreset`; you choose the presets with `setPartnerPreset`).\n What the session makes is filed for this managed user, and the lists it reads hold only this user's\n canvases, widgets and compositions. It can reach only canvases, widgets, compositions, repositories,\n uploaded files and operations made for this managed user (tag the canvases and widgets you create\n with `managedUserId`); any other canvas, widget, composition, conversation, message, repository, file\n or operation, including another of your users', answers 404. The creator also saves the composition\n it is editing (`updateComposition`, from the `editor` surface) and attaches pictures to its chat\n (`uploadsPost`, from the `files` surface), and the surfaces do not imply one another: to open the\n whole creator for a user, ask for `creator`, `editor` and `files` together. A generation or a build\n one user starts can be followed and cancelled by that user and by you, never by another of your\n users. The AI is paid for by your account, as your own calls are: its credits and allowances are\n yours. A session cannot make a widget public (publishing a version does not), file one under a\n project or an organization, or set anything the creator does not set: a body with another field is\n refused with 403 and `EDITOR_SESSION_FIELD_NOT_ALLOWED`.\n- `workflows`: use Widgetic's Workflows editor for this user. List their workflows and the compositions\n a workflow of theirs can chain (`listWorkspaceWorkflows`, `listWorkspaceWorkflowCompositionOptions`);\n list the starting points you offer them and make a workflow from one, which gives the user their own copy\n of every widget it chains, a composition of their own on each copy, and a draft\n (`listWorkspaceWorkflowPresets`, `createWorkspaceWorkflowFromPreset`; you offer them with\n `setPartnerWorkflowPreset`);\n make, open, change and delete one (`createWorkspaceWorkflow`, `getWorkspaceWorkflow`,\n `saveWorkspaceWorkflow`, `deleteWorkspaceWorkflow`) and copy it (`duplicateWorkspaceWorkflow`); publish\n it or discard the changes of its draft (`publishWorkspaceWorkflow`,\n `discardWorkspaceWorkflowChanges`); read and restore its versions (`listWorkspaceWorkflowVersions`,\n `getWorkspaceWorkflowVersion`, `restoreWorkspaceWorkflowVersion`); pause, resume, archive and unarchive it\n (`pauseWorkspaceWorkflow`, `resumeWorkspaceWorkflow`, `archiveWorkspaceWorkflow`,\n `unarchiveWorkspaceWorkflow`); and read its counts (`getWorkspaceWorkflowStats`). The workspace in each\n path is `personal`: a session has no other, and a path that names an organization is refused. What the\n session makes is filed for this managed user (`managedUserId`), the lists hold only this user's workflows,\n and it can reach only workflows made for this managed user; any other workflow, including one of yours\n or of another of your users, answers 404. A workflow can chain only the compositions you made for this\n managed user (tag them with `managedUserId`): one that belongs to anybody else is not available, and\n publishing a workflow that uses it is refused. A customer can have at most 50 workflows, and what a\n customer's session reads never says who published a version. A session cannot set who a workflow belongs\n to or which workspace it is in: a body with another field is refused with 403 and\n `EDITOR_SESSION_FIELD_NOT_ALLOWED`.\n\nEverything else is refused with 403 and `EDITOR_SESSION_ROUTE_NOT_ALLOWED`: a session cannot read your\naccount, make more sessions, change your presets or delete a composition, and a session without the `creator` surface cannot\ncreate or list compositions. Create the composition yourself with your API key, then open the editor on it.\n\nA session ends at `expiresAt` (at most four hours), when you end it (`revokeManagedUserEditorSession`),\nor when the managed user is switched off or deleted. A managed user can have at most 100 live sessions at\nonce (`429 EDITOR_SESSION_LIMIT_REACHED`). A session that is bound to a web page (`allowedOrigin`) is\nrefused from any other origin.\n\nThe AI the session runs is paid for with your credits. Set `maxCredits` to hold the session to a number\nof them: once its generations have taken that many (a generation that fails is refunded and does not\ncount), the next one is refused with 402 and `EDITOR_SESSION_CREDIT_LIMIT_REACHED`, and the browser is told\nonly that the feature is not available right now. Without it, the limit Widgetic has set for your account\napplies when it has set one (the same limit for every session you make, and `maxCredits: null` asks for\nnone), and otherwise the credits of your account are the only ceiling. What each of your users' sessions\nhas spent is in `getManagedUserUsage`.\n\nEach call makes a new session. It does not take an `Idempotency-Key`: the answer holds the token, and\nthe token is never stored where a retry could read it back. The answer is sent with\n`Cache-Control: no-store`.\n",
|
|
10550
10550
|
"tags": [
|
|
10551
10551
|
"Partner",
|
|
10552
10552
|
"Managed Users"
|
|
@@ -16726,7 +16726,7 @@
|
|
|
16726
16726
|
"post": {
|
|
16727
16727
|
"operationId": "addAiAnswersKnowledgeDocument",
|
|
16728
16728
|
"summary": "Add a document for a widget's AI to answer from",
|
|
16729
|
-
"description": "Gives the widget's AI a document to answer visitors' questions from. Send the title and the plain text. The call\nreturns once the document is ready to be used, which takes a few seconds, longer for a long text.\n\n**How it is used.** The text is cleaned, cut into short passages and each passage is turned into numbers (an\nembedding) so the widget can find the passages nearest to a question. When a visitor asks, the nearest passages and\nthe question are shown to an AI model, which writes the answer from them and from nothing else; if the documents\nsay nothing about the question the visitor is told so, and the owner is not charged for that question. The titles of\nthe documents an answer used are shown to the visitor as its sources.\n\n**What leaves Widgetic.** The text of a document is sent to OpenAI to be embedded when it is added, and the\npassages used for a question are sent to the AI model that writes the answer. Say so in your privacy policy.\n\n**Treat every document as public.** An answer can quote or paraphrase anything a document says, to any visitor of\nthe widget. Do not add passwords, keys, personal data or anything that must stay private.\n\n**Limits.** A widget holds up to 20 documents, each up to 100000 characters, and up to 400000 characters in all\n(`getAiAnswersKnowledge` reports the current numbers).
|
|
16729
|
+
"description": "Gives the widget's AI a document to answer visitors' questions from. Send the title and the plain text. The call\nreturns once the document is ready to be used, which takes a few seconds, longer for a long text.\n\n**How it is used.** The text is cleaned, cut into short passages and each passage is turned into numbers (an\nembedding) so the widget can find the passages nearest to a question. When a visitor asks, the nearest passages and\nthe question are shown to an AI model, which writes the answer from them and from nothing else; if the documents\nsay nothing about the question the visitor is told so, and the owner is not charged for that question. The titles of\nthe documents an answer used are shown to the visitor as its sources.\n\n**What leaves Widgetic.** The text of a document is sent to OpenAI to be embedded when it is added, and the\npassages used for a question are sent to the AI model that writes the answer. Say so in your privacy policy.\n\n**Treat every document as public.** An answer can quote or paraphrase anything a document says, to any visitor of\nthe widget. Do not add passwords, keys, personal data or anything that must stay private.\n\n**Limits.** A widget holds up to 20 documents, each up to 100000 characters, and up to 400000 characters in all\n(`getAiAnswersKnowledge` reports the current numbers). This call takes text. To add a text file or a picture of a\ndocument (a PDF too, once PDFs are read) without turning it into text yourself, use `addAiAnswersKnowledgeFile`. Adding a document costs no\ncredits. The same text cannot be added twice to one widget (409).\n\nThe caller must be allowed to change the widget. An API key needs the `content:write` scope. Adds are limited to ten\nin ten minutes per person. A partner's customer in an editor session is one person of its own: its adds are not\ncounted with the partner's other customers'.\n",
|
|
16730
16730
|
"tags": [
|
|
16731
16731
|
"Partner",
|
|
16732
16732
|
"Compositions"
|
|
@@ -16892,6 +16892,213 @@
|
|
|
16892
16892
|
]
|
|
16893
16893
|
}
|
|
16894
16894
|
},
|
|
16895
|
+
"/compositions/{id}/adapters/ai-answers/knowledge/documents/file": {
|
|
16896
|
+
"post": {
|
|
16897
|
+
"operationId": "addAiAnswersKnowledgeFile",
|
|
16898
|
+
"summary": "Add a text file or a picture of a document (a PDF once PDFs are read) for a widget's AI to answer from",
|
|
16899
|
+
"description": "Gives the widget's AI a document made from a file. Send a `multipart/form-data` request with the file in the field\nnamed `file` and, if you like, a `title`. The file is turned into text and then added exactly as\n`addAiAnswersKnowledgeDocument` adds text: the same cleaning, the same limits, the same refusal of a copy of a\ndocument the widget already has. The call returns once the document is ready to be used, which takes a few seconds\n(a PDF is read first, so it takes longer).\n\n**PDFs are not read yet.** For now a PDF is refused with 415, in a sentence that says what to do instead: paste the\ntext, upload it as a text file, or upload its pages as pictures. What this description says about a PDF is what will\nhold from the day PDFs are read.\n\n**Which files.**\n- A **PDF** (not read yet, see above), up to 10 MB and 300 pages. Its text is read and its paragraphs are put back\n together. A PDF that is only pictures of pages (a scan) has no text to read: upload the pages as pictures instead.\n A PDF locked with a password is refused.\n- A **text file**: `.txt`, `.text`, `.md`, `.markdown` or `.csv`, in UTF-8, UTF-16 or Windows-1252.\n- A **picture of a document**: PNG, JPEG or WebP, up to 4 MB. The text in it is read with the same text recognition\n as the `ocr` adapter.\n- Word and other office files are not read yet: save the file as a PDF and upload that.\n\nWhat a file is comes from what is in it, not from its name or the type it is sent as. A file that is none of these is\nrefused with 415.\n\n**The title.** Left out, the name of the file (without its extension) is the title. Visitors see the title as the\nsource of an answer, so send one that means something to them.\n\n**The file is not kept.** Only its text, cut into passages, is kept, and `getAiAnswersKnowledge` never returns it.\n\n**What leaves Widgetic.** As for text, the words of the document are sent to OpenAI to be embedded when it is added,\nand the passages used for a question are sent to the AI model that writes the answer. A picture is also sent to the\ntext recognition service. A PDF is read on Widgetic's own servers and is not sent anywhere to be read. Say so in your\nprivacy policy.\n\n**Treat every document as public.** An answer can quote or paraphrase anything a document says, to any visitor of\nthe widget. Do not add passwords, keys, personal data or anything that must stay private.\n\n**Limits.** The widget's limits are those of `addAiAnswersKnowledgeDocument` (up to 20 documents, each up to 100000\ncharacters of text, and up to 400000 characters in all; `getAiAnswersKnowledge` reports the current numbers), and\nthe file is at most 10 MB. Adding a document costs no credits. The same text cannot be added twice to one widget\n(409).\n\nThe caller must be allowed to change the widget. An API key needs the `content:write` scope. Adds, from text or from\na file, share one limit of ten in ten minutes per person. A partner's customer in an editor session is one person\nof its own: its adds are not counted with the partner's other customers'.\n",
|
|
16900
|
+
"tags": [
|
|
16901
|
+
"Partner",
|
|
16902
|
+
"Compositions"
|
|
16903
|
+
],
|
|
16904
|
+
"security": [
|
|
16905
|
+
{
|
|
16906
|
+
"apiKeyAuth": []
|
|
16907
|
+
}
|
|
16908
|
+
],
|
|
16909
|
+
"x-access-level": "user",
|
|
16910
|
+
"x-visibility": "public",
|
|
16911
|
+
"parameters": [
|
|
16912
|
+
{
|
|
16913
|
+
"in": "path",
|
|
16914
|
+
"name": "id",
|
|
16915
|
+
"required": true,
|
|
16916
|
+
"schema": {
|
|
16917
|
+
"type": "string",
|
|
16918
|
+
"format": "uuid"
|
|
16919
|
+
},
|
|
16920
|
+
"description": "The widget (composition) to add the document to"
|
|
16921
|
+
},
|
|
16922
|
+
{
|
|
16923
|
+
"$ref": "#/components/parameters/ManagedUserScopeId"
|
|
16924
|
+
},
|
|
16925
|
+
{
|
|
16926
|
+
"$ref": "#/components/parameters/ManagedUserScopeExternalId"
|
|
16927
|
+
}
|
|
16928
|
+
],
|
|
16929
|
+
"requestBody": {
|
|
16930
|
+
"required": true,
|
|
16931
|
+
"content": {
|
|
16932
|
+
"multipart/form-data": {
|
|
16933
|
+
"schema": {
|
|
16934
|
+
"type": "object",
|
|
16935
|
+
"required": [
|
|
16936
|
+
"file"
|
|
16937
|
+
],
|
|
16938
|
+
"additionalProperties": false,
|
|
16939
|
+
"properties": {
|
|
16940
|
+
"file": {
|
|
16941
|
+
"type": "string",
|
|
16942
|
+
"format": "binary",
|
|
16943
|
+
"description": "The file, which is a text file or a picture of a document (a PDF is not read yet). One file only"
|
|
16944
|
+
},
|
|
16945
|
+
"title": {
|
|
16946
|
+
"type": "string",
|
|
16947
|
+
"maxLength": 120,
|
|
16948
|
+
"description": "What the document is called, on one line. Visitors see it as the source of an answer. Left out, the name of the file stands in for it",
|
|
16949
|
+
"example": "Shipping and returns"
|
|
16950
|
+
}
|
|
16951
|
+
}
|
|
16952
|
+
}
|
|
16953
|
+
}
|
|
16954
|
+
}
|
|
16955
|
+
},
|
|
16956
|
+
"responses": {
|
|
16957
|
+
"201": {
|
|
16958
|
+
"description": "The document was added and is ready to be used",
|
|
16959
|
+
"content": {
|
|
16960
|
+
"application/json": {
|
|
16961
|
+
"schema": {
|
|
16962
|
+
"type": "object",
|
|
16963
|
+
"properties": {
|
|
16964
|
+
"success": {
|
|
16965
|
+
"type": "boolean"
|
|
16966
|
+
},
|
|
16967
|
+
"data": {
|
|
16968
|
+
"$ref": "#/components/schemas/AiAnswersKnowledgeDocument"
|
|
16969
|
+
},
|
|
16970
|
+
"meta": {
|
|
16971
|
+
"$ref": "#/components/schemas/ResponseMeta"
|
|
16972
|
+
}
|
|
16973
|
+
},
|
|
16974
|
+
"required": [
|
|
16975
|
+
"success",
|
|
16976
|
+
"data"
|
|
16977
|
+
]
|
|
16978
|
+
}
|
|
16979
|
+
}
|
|
16980
|
+
}
|
|
16981
|
+
},
|
|
16982
|
+
"400": {
|
|
16983
|
+
"description": "The widget id is not valid, no file was sent, more than one was, it was not in the field named `file`, the form could not be read, the form has a field other than `file` and `title`, or the title is too long (KNOWLEDGE_FILE_REQUIRED, KNOWLEDGE_TITLE_REQUIRED, KNOWLEDGE_TITLE_TOO_LONG, KNOWLEDGE_TEXT_REQUIRED)",
|
|
16984
|
+
"content": {
|
|
16985
|
+
"application/json": {
|
|
16986
|
+
"schema": {
|
|
16987
|
+
"$ref": "#/components/schemas/ErrorResponse"
|
|
16988
|
+
}
|
|
16989
|
+
}
|
|
16990
|
+
}
|
|
16991
|
+
},
|
|
16992
|
+
"401": {
|
|
16993
|
+
"description": "The API key is missing or invalid",
|
|
16994
|
+
"content": {
|
|
16995
|
+
"application/json": {
|
|
16996
|
+
"schema": {
|
|
16997
|
+
"$ref": "#/components/schemas/ErrorResponse"
|
|
16998
|
+
}
|
|
16999
|
+
}
|
|
17000
|
+
}
|
|
17001
|
+
},
|
|
17002
|
+
"403": {
|
|
17003
|
+
"description": "The widget belongs to another account, or the API key lacks the `content:write` scope",
|
|
17004
|
+
"content": {
|
|
17005
|
+
"application/json": {
|
|
17006
|
+
"schema": {
|
|
17007
|
+
"$ref": "#/components/schemas/ErrorResponse"
|
|
17008
|
+
}
|
|
17009
|
+
}
|
|
17010
|
+
}
|
|
17011
|
+
},
|
|
17012
|
+
"404": {
|
|
17013
|
+
"description": "There is no such widget",
|
|
17014
|
+
"content": {
|
|
17015
|
+
"application/json": {
|
|
17016
|
+
"schema": {
|
|
17017
|
+
"$ref": "#/components/schemas/ErrorResponse"
|
|
17018
|
+
}
|
|
17019
|
+
}
|
|
17020
|
+
}
|
|
17021
|
+
},
|
|
17022
|
+
"409": {
|
|
17023
|
+
"description": "The same text is already in this widget, or the widget already holds the most documents it can (KNOWLEDGE_DUPLICATE_DOCUMENT, KNOWLEDGE_LIMIT_DOCUMENTS)",
|
|
17024
|
+
"content": {
|
|
17025
|
+
"application/json": {
|
|
17026
|
+
"schema": {
|
|
17027
|
+
"$ref": "#/components/schemas/ErrorResponse"
|
|
17028
|
+
}
|
|
17029
|
+
}
|
|
17030
|
+
}
|
|
17031
|
+
},
|
|
17032
|
+
"413": {
|
|
17033
|
+
"description": "The file is larger than 10 MB, a PDF has more than 300 pages, a picture is larger than 4 MB, or the text of the file is longer than a document may be or would take the widget past the most text it can hold in all (KNOWLEDGE_FILE_TOO_LARGE, KNOWLEDGE_TEXT_TOO_LONG, KNOWLEDGE_LIMIT_TOTAL_TEXT). Nothing was saved",
|
|
17034
|
+
"content": {
|
|
17035
|
+
"application/json": {
|
|
17036
|
+
"schema": {
|
|
17037
|
+
"$ref": "#/components/schemas/ErrorResponse"
|
|
17038
|
+
}
|
|
17039
|
+
}
|
|
17040
|
+
}
|
|
17041
|
+
},
|
|
17042
|
+
"415": {
|
|
17043
|
+
"description": "The file is not a text file or a PNG, JPEG or WebP picture, or it is a PDF or a Word or other office file, which are not read yet (KNOWLEDGE_FILE_TYPE_UNSUPPORTED)",
|
|
17044
|
+
"content": {
|
|
17045
|
+
"application/json": {
|
|
17046
|
+
"schema": {
|
|
17047
|
+
"$ref": "#/components/schemas/ErrorResponse"
|
|
17048
|
+
}
|
|
17049
|
+
}
|
|
17050
|
+
}
|
|
17051
|
+
},
|
|
17052
|
+
"422": {
|
|
17053
|
+
"description": "The file is of a kind that is read but this one cannot be: a PDF that is damaged, locked with a password or too slow to read, or a PDF or a picture with no text in it (KNOWLEDGE_FILE_UNREADABLE, KNOWLEDGE_FILE_NO_TEXT)",
|
|
17054
|
+
"content": {
|
|
17055
|
+
"application/json": {
|
|
17056
|
+
"schema": {
|
|
17057
|
+
"$ref": "#/components/schemas/ErrorResponse"
|
|
17058
|
+
}
|
|
17059
|
+
}
|
|
17060
|
+
}
|
|
17061
|
+
},
|
|
17062
|
+
"429": {
|
|
17063
|
+
"description": "Too many documents added in a short time. Try again after the Retry-After seconds.",
|
|
17064
|
+
"content": {
|
|
17065
|
+
"application/json": {
|
|
17066
|
+
"schema": {
|
|
17067
|
+
"$ref": "#/components/schemas/ErrorResponse"
|
|
17068
|
+
}
|
|
17069
|
+
}
|
|
17070
|
+
}
|
|
17071
|
+
},
|
|
17072
|
+
"502": {
|
|
17073
|
+
"description": "The document could not be processed or saved (KNOWLEDGE_NOT_COMPLETED). Nothing was saved: try again",
|
|
17074
|
+
"content": {
|
|
17075
|
+
"application/json": {
|
|
17076
|
+
"schema": {
|
|
17077
|
+
"$ref": "#/components/schemas/ErrorResponse"
|
|
17078
|
+
}
|
|
17079
|
+
}
|
|
17080
|
+
}
|
|
17081
|
+
},
|
|
17082
|
+
"503": {
|
|
17083
|
+
"description": "The knowledge base is not available right now, or the service is busy (KNOWLEDGE_UNAVAILABLE, KNOWLEDGE_BUSY). Nothing was saved",
|
|
17084
|
+
"content": {
|
|
17085
|
+
"application/json": {
|
|
17086
|
+
"schema": {
|
|
17087
|
+
"$ref": "#/components/schemas/ErrorResponse"
|
|
17088
|
+
}
|
|
17089
|
+
}
|
|
17090
|
+
}
|
|
17091
|
+
}
|
|
17092
|
+
},
|
|
17093
|
+
"x-code-samples": [
|
|
17094
|
+
{
|
|
17095
|
+
"lang": "TypeScript",
|
|
17096
|
+
"label": "TypeScript SDK",
|
|
17097
|
+
"source": "import { openAsBlob } from 'node:fs';\nimport { Configuration, CompositionsApi } from '@widgetic/api-sdk-ts';\n\nconst compositionsApi = new CompositionsApi(new Configuration({ apiKey: 'YOUR_API_KEY' }));\n\nconst document = await compositionsApi.addAiAnswersKnowledgeFile({\n id: compositionId,\n file: await openAsBlob('shipping-and-returns.pdf'),\n title: 'Shipping and returns',\n});\nconsole.log(document.id, document.status);\n"
|
|
17098
|
+
}
|
|
17099
|
+
]
|
|
17100
|
+
}
|
|
17101
|
+
},
|
|
16895
17102
|
"/compositions/{id}/adapters/ai-answers/knowledge/documents/{documentId}": {
|
|
16896
17103
|
"delete": {
|
|
16897
17104
|
"operationId": "removeAiAnswersKnowledgeDocument",
|
|
@@ -17153,7 +17360,7 @@
|
|
|
17153
17360
|
"put": {
|
|
17154
17361
|
"operationId": "setUserAdapterConnection",
|
|
17155
17362
|
"summary": "Connect an adapter key to an account",
|
|
17156
|
-
"description": "Gives an adapter the key it needs to act through a service you have an account with, for the widgets you made.\nTake the `adapterId` and `credentialKey` from `getUserAdapterConnections`. Saving a key that is already\nconnected replaces it.\n\n**What Widgetic does with it.** The key is stored encrypted, bound to this account, this adapter and this\ncredential, so that a stored value cannot be moved to another. It is never returned, never logged and never\nshown to a visitor of a widget. A server of Widgetic opens it for the one call a widget makes through the\nadapter, uses it to call the provider on your behalf, and discards it. To cut that off, remove the key here, or\nrevoke it with the provider.\n\n**What is checked.** That the adapter exists and takes this credential, that an owner may keep it (some are\nfor a partner only) and that the text is one line of at most 2048 characters. Whether the provider accepts\nthe key is not checked here: it shows the first time a widget uses it, and the widget tells its owner.\n\nA widget whose adapter has no key connected is not charged and does not
|
|
17363
|
+
"description": "Gives an adapter the key it needs to act through a service you have an account with, for the widgets you made.\nTake the `adapterId` and `credentialKey` from `getUserAdapterConnections`. Saving a key that is already\nconnected replaces it.\n\n**What Widgetic does with it.** The key is stored encrypted, bound to this account, this adapter and this\ncredential, so that a stored value cannot be moved to another. It is never returned, never logged and never\nshown to a visitor of a widget. A server of Widgetic opens it for the one call a widget makes through the\nadapter, uses it to call the provider on your behalf, and discards it. To cut that off, remove the key here, or\nrevoke it with the provider.\n\n**What is checked.** That the adapter exists and takes this credential, that an owner may keep it (some are\nfor a partner only) and that the text is one line of at most 2048 characters. Whether the provider accepts\nthe key is not checked here: it shows the first time a widget uses it, and the widget tells its owner.\n\n**An address that has to be confirmed.** Some credentials are not a key but the email address Widgetic sends a\nwidget's messages to (`confirmation: email_code` in `getUserAdapterConnections`). Saving one checks that it is one\nemail address and emails a six-digit code to it; the answer says `awaitingConfirmation: true`, and nothing is sent\nto the address until the code is given back with `confirmUserAdapterConnection`. Saving the same address again\nbefore it is confirmed emails a new code (not sooner than a minute after the last); saving the address that is\nalready confirmed changes nothing. If the code cannot be emailed, nothing is saved.\n\nA widget whose adapter has no key connected, or whose address is not confirmed yet, is not charged and does not\nrun that adapter: its visitors are told the feature is unavailable, and the owner is told once a day what to do.\n\nThis needs an API key with full access. The caller must be the account itself or a Widgetic administrator. A\nretry is harmless: saving the same key twice only refreshes when it was set.\n",
|
|
17157
17364
|
"tags": [
|
|
17158
17365
|
"Partner",
|
|
17159
17366
|
"Users"
|
|
@@ -17274,7 +17481,139 @@
|
|
|
17274
17481
|
}
|
|
17275
17482
|
},
|
|
17276
17483
|
"422": {
|
|
17277
|
-
"description": "The credential is not one line of text of at most 2048 characters (CREDENTIAL_VALUE_INVALID). Nothing was saved",
|
|
17484
|
+
"description": "The credential is not one line of text of at most 2048 characters (CREDENTIAL_VALUE_INVALID), is not one email address where one is needed (CREDENTIAL_ADDRESS_INVALID), or the email provider refused the address a code was to be emailed to (CONFIRMATION_ADDRESS_REFUSED). Nothing was saved",
|
|
17485
|
+
"content": {
|
|
17486
|
+
"application/json": {
|
|
17487
|
+
"schema": {
|
|
17488
|
+
"$ref": "#/components/schemas/ErrorResponse"
|
|
17489
|
+
}
|
|
17490
|
+
}
|
|
17491
|
+
}
|
|
17492
|
+
},
|
|
17493
|
+
"429": {
|
|
17494
|
+
"description": "Too many changes in a short time (try again after the Retry-After seconds), or too many codes were emailed to that address or for that account (CONFIRMATION_TOO_SOON, CONFIRMATION_LIMIT_REACHED)",
|
|
17495
|
+
"content": {
|
|
17496
|
+
"application/json": {
|
|
17497
|
+
"schema": {
|
|
17498
|
+
"$ref": "#/components/schemas/ErrorResponse"
|
|
17499
|
+
}
|
|
17500
|
+
}
|
|
17501
|
+
}
|
|
17502
|
+
},
|
|
17503
|
+
"503": {
|
|
17504
|
+
"description": "Adapter keys cannot be saved on this server right now (ADAPTER_CONNECTIONS_UNAVAILABLE), or the code could not be emailed (CONFIRMATION_NOT_SENT). Nothing was changed",
|
|
17505
|
+
"content": {
|
|
17506
|
+
"application/json": {
|
|
17507
|
+
"schema": {
|
|
17508
|
+
"$ref": "#/components/schemas/ErrorResponse"
|
|
17509
|
+
}
|
|
17510
|
+
}
|
|
17511
|
+
}
|
|
17512
|
+
}
|
|
17513
|
+
},
|
|
17514
|
+
"x-code-samples": [
|
|
17515
|
+
{
|
|
17516
|
+
"lang": "TypeScript",
|
|
17517
|
+
"label": "TypeScript SDK",
|
|
17518
|
+
"source": "import { Configuration, UsersApi } from '@widgetic/api-sdk-ts';\n\nconst usersApi = new UsersApi(new Configuration({ apiKey: 'YOUR_API_KEY' }));\n\nconst connection = await usersApi.setUserAdapterConnection({\n userId,\n adapterId: 'email',\n credentialKey: 'resendApiKey',\n setAdapterConnectionRequest: { credential: 'YOUR_PROVIDER_KEY' },\n});\nconsole.log(connection.connected, connection.updatedAt);\n\n// An address a widget's messages are emailed to: a code is emailed to it, and it is used once the code is given back.\nconst address = await usersApi.setUserAdapterConnection({\n userId,\n adapterId: 'email',\n credentialKey: 'recipient',\n setAdapterConnectionRequest: { credential: 'owner@example.com' },\n});\nconsole.log(address.awaitingConfirmation);\n"
|
|
17519
|
+
}
|
|
17520
|
+
]
|
|
17521
|
+
},
|
|
17522
|
+
"delete": {
|
|
17523
|
+
"operationId": "removeUserAdapterConnection",
|
|
17524
|
+
"summary": "Remove an adapter key from an account",
|
|
17525
|
+
"description": "Removes a key an adapter was given. The adapter stops working for the widgets that need it: their visitors are\ntold the feature is unavailable. Nothing else of the widgets changes, and connecting a key again brings them\nback.\n\nRemoving a key that is not connected answers 200 with `removed: false`: the state asked for is the state it is\nin. A key of an adapter that has since been retired from the catalog can still be removed.\n\nThis needs an API key with full access. The caller must be the account itself or a Widgetic administrator.\n",
|
|
17526
|
+
"tags": [
|
|
17527
|
+
"Partner",
|
|
17528
|
+
"Users"
|
|
17529
|
+
],
|
|
17530
|
+
"security": [
|
|
17531
|
+
{
|
|
17532
|
+
"apiKeyAuth": []
|
|
17533
|
+
}
|
|
17534
|
+
],
|
|
17535
|
+
"x-access-level": "user",
|
|
17536
|
+
"x-visibility": "public",
|
|
17537
|
+
"parameters": [
|
|
17538
|
+
{
|
|
17539
|
+
"in": "path",
|
|
17540
|
+
"name": "userId",
|
|
17541
|
+
"required": true,
|
|
17542
|
+
"schema": {
|
|
17543
|
+
"type": "string",
|
|
17544
|
+
"format": "uuid"
|
|
17545
|
+
},
|
|
17546
|
+
"description": "The account that keeps the key. For your own, your own user id"
|
|
17547
|
+
},
|
|
17548
|
+
{
|
|
17549
|
+
"in": "path",
|
|
17550
|
+
"name": "adapterId",
|
|
17551
|
+
"required": true,
|
|
17552
|
+
"schema": {
|
|
17553
|
+
"type": "string",
|
|
17554
|
+
"maxLength": 40
|
|
17555
|
+
},
|
|
17556
|
+
"description": "The adapter the key is for"
|
|
17557
|
+
},
|
|
17558
|
+
{
|
|
17559
|
+
"in": "path",
|
|
17560
|
+
"name": "credentialKey",
|
|
17561
|
+
"required": true,
|
|
17562
|
+
"schema": {
|
|
17563
|
+
"type": "string",
|
|
17564
|
+
"maxLength": 40
|
|
17565
|
+
},
|
|
17566
|
+
"description": "The key's name within the adapter"
|
|
17567
|
+
}
|
|
17568
|
+
],
|
|
17569
|
+
"responses": {
|
|
17570
|
+
"200": {
|
|
17571
|
+
"description": "The key is not connected any more",
|
|
17572
|
+
"content": {
|
|
17573
|
+
"application/json": {
|
|
17574
|
+
"schema": {
|
|
17575
|
+
"type": "object",
|
|
17576
|
+
"properties": {
|
|
17577
|
+
"success": {
|
|
17578
|
+
"type": "boolean"
|
|
17579
|
+
},
|
|
17580
|
+
"data": {
|
|
17581
|
+
"$ref": "#/components/schemas/AdapterConnectionRemoval"
|
|
17582
|
+
},
|
|
17583
|
+
"meta": {
|
|
17584
|
+
"$ref": "#/components/schemas/ResponseMeta"
|
|
17585
|
+
}
|
|
17586
|
+
},
|
|
17587
|
+
"required": [
|
|
17588
|
+
"success",
|
|
17589
|
+
"data"
|
|
17590
|
+
]
|
|
17591
|
+
}
|
|
17592
|
+
}
|
|
17593
|
+
}
|
|
17594
|
+
},
|
|
17595
|
+
"400": {
|
|
17596
|
+
"description": "A path value is malformed",
|
|
17597
|
+
"content": {
|
|
17598
|
+
"application/json": {
|
|
17599
|
+
"schema": {
|
|
17600
|
+
"$ref": "#/components/schemas/ErrorResponse"
|
|
17601
|
+
}
|
|
17602
|
+
}
|
|
17603
|
+
}
|
|
17604
|
+
},
|
|
17605
|
+
"401": {
|
|
17606
|
+
"description": "The API key is missing or invalid",
|
|
17607
|
+
"content": {
|
|
17608
|
+
"application/json": {
|
|
17609
|
+
"schema": {
|
|
17610
|
+
"$ref": "#/components/schemas/ErrorResponse"
|
|
17611
|
+
}
|
|
17612
|
+
}
|
|
17613
|
+
}
|
|
17614
|
+
},
|
|
17615
|
+
"403": {
|
|
17616
|
+
"description": "The key belongs to another account, or the API key has not full access",
|
|
17278
17617
|
"content": {
|
|
17279
17618
|
"application/json": {
|
|
17280
17619
|
"schema": {
|
|
@@ -17294,7 +17633,7 @@
|
|
|
17294
17633
|
}
|
|
17295
17634
|
},
|
|
17296
17635
|
"503": {
|
|
17297
|
-
"description": "Adapter keys cannot be
|
|
17636
|
+
"description": "Adapter keys cannot be changed on this server right now (ADAPTER_CONNECTIONS_UNAVAILABLE). Nothing was changed",
|
|
17298
17637
|
"content": {
|
|
17299
17638
|
"application/json": {
|
|
17300
17639
|
"schema": {
|
|
@@ -17308,14 +17647,16 @@
|
|
|
17308
17647
|
{
|
|
17309
17648
|
"lang": "TypeScript",
|
|
17310
17649
|
"label": "TypeScript SDK",
|
|
17311
|
-
"source": "import { Configuration, UsersApi } from '@widgetic/api-sdk-ts';\n\nconst usersApi = new UsersApi(new Configuration({ apiKey: 'YOUR_API_KEY' }));\n\nconst
|
|
17650
|
+
"source": "import { Configuration, UsersApi } from '@widgetic/api-sdk-ts';\n\nconst usersApi = new UsersApi(new Configuration({ apiKey: 'YOUR_API_KEY' }));\n\nconst { removed } = await usersApi.removeUserAdapterConnection({\n userId,\n adapterId: 'email',\n credentialKey: 'resendApiKey',\n});\n"
|
|
17312
17651
|
}
|
|
17313
17652
|
]
|
|
17314
|
-
}
|
|
17315
|
-
|
|
17316
|
-
|
|
17317
|
-
|
|
17318
|
-
"
|
|
17653
|
+
}
|
|
17654
|
+
},
|
|
17655
|
+
"/users/{userId}/adapter-connections/{adapterId}/{credentialKey}/confirm": {
|
|
17656
|
+
"post": {
|
|
17657
|
+
"operationId": "confirmUserAdapterConnection",
|
|
17658
|
+
"summary": "Confirm an adapter address with the code that was emailed to it",
|
|
17659
|
+
"description": "Some credentials are an email address Widgetic sends a widget's messages to (`confirmation: email_code` in\n`getUserAdapterConnections`). Saving one with `setUserAdapterConnection` emails a six-digit code to it; this gives\nthe code back. Only then is the address used: until it is confirmed, the widgets that need it are not charged and\ntheir visitors are told the feature is unavailable.\n\nThe code works for 30 minutes and for five wrong tries. After that, save the address again and a new code is\nemailed (not sooner than a minute after the last one). A code that is not made of digits is refused without\ncounting as a try.\n\nConfirming an address that is already confirmed answers 200 with the same state, so a retry of a request that\nwent through is harmless. Saving a different address, or the same one before it was confirmed, starts again.\n\nThis needs an API key with full access. The caller must be the account itself or a Widgetic administrator.\n",
|
|
17319
17660
|
"tags": [
|
|
17320
17661
|
"Partner",
|
|
17321
17662
|
"Users"
|
|
@@ -17336,7 +17677,7 @@
|
|
|
17336
17677
|
"type": "string",
|
|
17337
17678
|
"format": "uuid"
|
|
17338
17679
|
},
|
|
17339
|
-
"description": "The account that keeps the
|
|
17680
|
+
"description": "The account that keeps the address. For your own, your own user id"
|
|
17340
17681
|
},
|
|
17341
17682
|
{
|
|
17342
17683
|
"in": "path",
|
|
@@ -17346,7 +17687,7 @@
|
|
|
17346
17687
|
"type": "string",
|
|
17347
17688
|
"maxLength": 40
|
|
17348
17689
|
},
|
|
17349
|
-
"description": "The adapter the
|
|
17690
|
+
"description": "The adapter the address is for"
|
|
17350
17691
|
},
|
|
17351
17692
|
{
|
|
17352
17693
|
"in": "path",
|
|
@@ -17356,12 +17697,22 @@
|
|
|
17356
17697
|
"type": "string",
|
|
17357
17698
|
"maxLength": 40
|
|
17358
17699
|
},
|
|
17359
|
-
"description": "The
|
|
17700
|
+
"description": "The credential's name within the adapter"
|
|
17360
17701
|
}
|
|
17361
17702
|
],
|
|
17703
|
+
"requestBody": {
|
|
17704
|
+
"required": true,
|
|
17705
|
+
"content": {
|
|
17706
|
+
"application/json": {
|
|
17707
|
+
"schema": {
|
|
17708
|
+
"$ref": "#/components/schemas/ConfirmAdapterConnectionRequest"
|
|
17709
|
+
}
|
|
17710
|
+
}
|
|
17711
|
+
}
|
|
17712
|
+
},
|
|
17362
17713
|
"responses": {
|
|
17363
17714
|
"200": {
|
|
17364
|
-
"description": "The
|
|
17715
|
+
"description": "The address is confirmed (or was already)",
|
|
17365
17716
|
"content": {
|
|
17366
17717
|
"application/json": {
|
|
17367
17718
|
"schema": {
|
|
@@ -17371,7 +17722,7 @@
|
|
|
17371
17722
|
"type": "boolean"
|
|
17372
17723
|
},
|
|
17373
17724
|
"data": {
|
|
17374
|
-
"$ref": "#/components/schemas/
|
|
17725
|
+
"$ref": "#/components/schemas/AdapterConnection"
|
|
17375
17726
|
},
|
|
17376
17727
|
"meta": {
|
|
17377
17728
|
"$ref": "#/components/schemas/ResponseMeta"
|
|
@@ -17386,7 +17737,7 @@
|
|
|
17386
17737
|
}
|
|
17387
17738
|
},
|
|
17388
17739
|
"400": {
|
|
17389
|
-
"description": "A path value is malformed",
|
|
17740
|
+
"description": "A path value or the body is malformed. The body takes exactly one field, `code`",
|
|
17390
17741
|
"content": {
|
|
17391
17742
|
"application/json": {
|
|
17392
17743
|
"schema": {
|
|
@@ -17406,7 +17757,37 @@
|
|
|
17406
17757
|
}
|
|
17407
17758
|
},
|
|
17408
17759
|
"403": {
|
|
17409
|
-
"description": "The
|
|
17760
|
+
"description": "The address belongs to another account, or the API key has not full access",
|
|
17761
|
+
"content": {
|
|
17762
|
+
"application/json": {
|
|
17763
|
+
"schema": {
|
|
17764
|
+
"$ref": "#/components/schemas/ErrorResponse"
|
|
17765
|
+
}
|
|
17766
|
+
}
|
|
17767
|
+
}
|
|
17768
|
+
},
|
|
17769
|
+
"404": {
|
|
17770
|
+
"description": "There is no such adapter or credential, an owner may not keep it, the credential needs no confirmation, or nothing is connected under that name (ADAPTER_NOT_FOUND, CREDENTIAL_NOT_FOUND, CREDENTIAL_NOT_FOR_THIS_ACCOUNT, CONFIRMATION_NOT_NEEDED, CREDENTIAL_NOT_CONNECTED)",
|
|
17771
|
+
"content": {
|
|
17772
|
+
"application/json": {
|
|
17773
|
+
"schema": {
|
|
17774
|
+
"$ref": "#/components/schemas/ErrorResponse"
|
|
17775
|
+
}
|
|
17776
|
+
}
|
|
17777
|
+
}
|
|
17778
|
+
},
|
|
17779
|
+
"409": {
|
|
17780
|
+
"description": "No code is waiting for the address (CONFIRMATION_NO_CODE_WAITING), or another attempt is being checked, or the address was saved again while this one was checked (CONFIRMATION_BUSY). Save the address again, or retry",
|
|
17781
|
+
"content": {
|
|
17782
|
+
"application/json": {
|
|
17783
|
+
"schema": {
|
|
17784
|
+
"$ref": "#/components/schemas/ErrorResponse"
|
|
17785
|
+
}
|
|
17786
|
+
}
|
|
17787
|
+
}
|
|
17788
|
+
},
|
|
17789
|
+
"422": {
|
|
17790
|
+
"description": "The code is not made of digits (CONFIRMATION_CODE_INVALID), is not the one emailed (CONFIRMATION_CODE_WRONG; it counts as a try) or is too old (CONFIRMATION_CODE_EXPIRED)",
|
|
17410
17791
|
"content": {
|
|
17411
17792
|
"application/json": {
|
|
17412
17793
|
"schema": {
|
|
@@ -17416,7 +17797,7 @@
|
|
|
17416
17797
|
}
|
|
17417
17798
|
},
|
|
17418
17799
|
"429": {
|
|
17419
|
-
"description": "Too many changes in a short time
|
|
17800
|
+
"description": "Too many changes in a short time (try again after the Retry-After seconds), or five wrong codes were given and the code is dead (CONFIRMATION_TOO_MANY_ATTEMPTS): save the address again for a new one",
|
|
17420
17801
|
"content": {
|
|
17421
17802
|
"application/json": {
|
|
17422
17803
|
"schema": {
|
|
@@ -17440,7 +17821,7 @@
|
|
|
17440
17821
|
{
|
|
17441
17822
|
"lang": "TypeScript",
|
|
17442
17823
|
"label": "TypeScript SDK",
|
|
17443
|
-
"source": "import { Configuration, UsersApi } from '@widgetic/api-sdk-ts';\n\nconst usersApi = new UsersApi(new Configuration({ apiKey: 'YOUR_API_KEY' }));\n\
|
|
17824
|
+
"source": "import { Configuration, UsersApi } from '@widgetic/api-sdk-ts';\n\nconst usersApi = new UsersApi(new Configuration({ apiKey: 'YOUR_API_KEY' }));\n\n// After setUserAdapterConnection emailed a code to the address:\nconst connection = await usersApi.confirmUserAdapterConnection({\n userId,\n adapterId: 'email',\n credentialKey: 'recipient',\n confirmAdapterConnectionRequest: { code: '123456' },\n});\nconsole.log(connection.awaitingConfirmation, connection.confirmedAt);\n"
|
|
17444
17825
|
}
|
|
17445
17826
|
]
|
|
17446
17827
|
}
|
|
@@ -17566,7 +17947,7 @@
|
|
|
17566
17947
|
"put": {
|
|
17567
17948
|
"operationId": "setPartnerAdapterConnection",
|
|
17568
17949
|
"summary": "Connect an adapter key to a partner",
|
|
17569
|
-
"description": "Gives an adapter the key it needs to act through a service the partner has an account with, for the widgets of\nthe customers the partner manages. Take the `adapterId` and `credentialKey` from\n`getPartnerAdapterConnections`. Saving a key that is already connected replaces it.\n\n**What Widgetic does with it.** The key is stored encrypted, bound to this partner, this adapter and this\ncredential, so that a stored value cannot be moved to another. It is never returned, never logged and never\nshown to a visitor of a widget or to your customers. A server of Widgetic opens it for the one call a widget\nmakes through the adapter, uses it to call the provider on the partner's behalf, and discards it. To cut that\noff, remove the key here, or revoke it with the provider.\n\n**What is checked.** That the adapter exists and takes this credential, that a partner may keep it (some are\nfor an owner only) and that the text is one line of at most 2048 characters. Whether the provider accepts the\nkey is not checked here: it shows the first time a widget uses it.\n\nA widget whose adapter has no key connected is not charged and does not
|
|
17950
|
+
"description": "Gives an adapter the key it needs to act through a service the partner has an account with, for the widgets of\nthe customers the partner manages. Take the `adapterId` and `credentialKey` from\n`getPartnerAdapterConnections`. Saving a key that is already connected replaces it.\n\n**What Widgetic does with it.** The key is stored encrypted, bound to this partner, this adapter and this\ncredential, so that a stored value cannot be moved to another. It is never returned, never logged and never\nshown to a visitor of a widget or to your customers. A server of Widgetic opens it for the one call a widget\nmakes through the adapter, uses it to call the provider on the partner's behalf, and discards it. To cut that\noff, remove the key here, or revoke it with the provider.\n\n**What is checked.** That the adapter exists and takes this credential, that a partner may keep it (some are\nfor an owner only) and that the text is one line of at most 2048 characters. Whether the provider accepts the\nkey is not checked here: it shows the first time a widget uses it.\n\n**An address that has to be confirmed.** Some credentials are not a key but the email address Widgetic sends a\nwidget's messages to (`confirmation: email_code` in `getPartnerAdapterConnections`). Saving one checks that it is\none email address and emails a six-digit code to it; the answer says `awaitingConfirmation: true`, and nothing is\nsent to the address until the code is given back with `confirmPartnerAdapterConnection`. Saving the same address\nagain before it is confirmed emails a new code (not sooner than a minute after the last); saving the address that\nis already confirmed changes nothing. If the code cannot be emailed, nothing is saved.\n\nA widget whose adapter has no key connected, or whose address is not confirmed yet, is not charged and does not\nrun that adapter: its visitors are told the feature is unavailable, and the partner is told once a day what to do.\n\nThis needs an API key with full access. The caller must be the person who administers the partner, or a\nWidgetic administrator. A retry is harmless: saving the same key twice only refreshes when it was set.\n",
|
|
17570
17951
|
"tags": [
|
|
17571
17952
|
"Partner",
|
|
17572
17953
|
"Partners"
|
|
@@ -17687,7 +18068,7 @@
|
|
|
17687
18068
|
}
|
|
17688
18069
|
},
|
|
17689
18070
|
"422": {
|
|
17690
|
-
"description": "The credential is not one line of text of at most 2048 characters (CREDENTIAL_VALUE_INVALID). Nothing was saved",
|
|
18071
|
+
"description": "The credential is not one line of text of at most 2048 characters (CREDENTIAL_VALUE_INVALID), is not one email address where one is needed (CREDENTIAL_ADDRESS_INVALID), or the email provider refused the address a code was to be emailed to (CONFIRMATION_ADDRESS_REFUSED). Nothing was saved",
|
|
17691
18072
|
"content": {
|
|
17692
18073
|
"application/json": {
|
|
17693
18074
|
"schema": {
|
|
@@ -17697,7 +18078,7 @@
|
|
|
17697
18078
|
}
|
|
17698
18079
|
},
|
|
17699
18080
|
"429": {
|
|
17700
|
-
"description": "Too many changes in a short time
|
|
18081
|
+
"description": "Too many changes in a short time (try again after the Retry-After seconds), or too many codes were emailed to that address or for that account (CONFIRMATION_TOO_SOON, CONFIRMATION_LIMIT_REACHED)",
|
|
17701
18082
|
"content": {
|
|
17702
18083
|
"application/json": {
|
|
17703
18084
|
"schema": {
|
|
@@ -17707,7 +18088,7 @@
|
|
|
17707
18088
|
}
|
|
17708
18089
|
},
|
|
17709
18090
|
"503": {
|
|
17710
|
-
"description": "Adapter keys cannot be saved on this server right now (ADAPTER_CONNECTIONS_UNAVAILABLE). Nothing was changed",
|
|
18091
|
+
"description": "Adapter keys cannot be saved on this server right now (ADAPTER_CONNECTIONS_UNAVAILABLE), or the code could not be emailed (CONFIRMATION_NOT_SENT). Nothing was changed",
|
|
17711
18092
|
"content": {
|
|
17712
18093
|
"application/json": {
|
|
17713
18094
|
"schema": {
|
|
@@ -17721,7 +18102,7 @@
|
|
|
17721
18102
|
{
|
|
17722
18103
|
"lang": "TypeScript",
|
|
17723
18104
|
"label": "TypeScript SDK",
|
|
17724
|
-
"source": "import { Configuration, PartnersApi } from '@widgetic/api-sdk-ts';\n\nconst partnersApi = new PartnersApi(new Configuration({ apiKey: 'YOUR_API_KEY' }));\n\nconst connection = await partnersApi.setPartnerAdapterConnection({\n partnerId,\n adapterId: 'email',\n credentialKey: 'resendApiKey',\n setAdapterConnectionRequest: { credential: 'YOUR_PROVIDER_KEY' },\n});\nconsole.log(connection.connected, connection.updatedAt);\n"
|
|
18105
|
+
"source": "import { Configuration, PartnersApi } from '@widgetic/api-sdk-ts';\n\nconst partnersApi = new PartnersApi(new Configuration({ apiKey: 'YOUR_API_KEY' }));\n\nconst connection = await partnersApi.setPartnerAdapterConnection({\n partnerId,\n adapterId: 'email',\n credentialKey: 'resendApiKey',\n setAdapterConnectionRequest: { credential: 'YOUR_PROVIDER_KEY' },\n});\nconsole.log(connection.connected, connection.updatedAt);\n\n// An address a widget's messages are emailed to: a code is emailed to it, and it is used once the code is given back.\nconst address = await partnersApi.setPartnerAdapterConnection({\n partnerId,\n adapterId: 'email',\n credentialKey: 'recipient',\n setAdapterConnectionRequest: { credential: 'owner@example.com' },\n});\nconsole.log(address.awaitingConfirmation);\n"
|
|
17725
18106
|
}
|
|
17726
18107
|
]
|
|
17727
18108
|
},
|
|
@@ -17857,6 +18238,180 @@
|
|
|
17857
18238
|
}
|
|
17858
18239
|
]
|
|
17859
18240
|
}
|
|
18241
|
+
},
|
|
18242
|
+
"/partners/{partnerId}/adapter-connections/{adapterId}/{credentialKey}/confirm": {
|
|
18243
|
+
"post": {
|
|
18244
|
+
"operationId": "confirmPartnerAdapterConnection",
|
|
18245
|
+
"summary": "Confirm a partner's adapter address with the code that was emailed to it",
|
|
18246
|
+
"description": "Some credentials are an email address Widgetic sends a widget's messages to (`confirmation: email_code` in\n`getPartnerAdapterConnections`). Saving one with `setPartnerAdapterConnection` emails a six-digit code to it; this\ngives the code back. Only then is the address used: until it is confirmed, the widgets of the partner's customers\nthat need it are not charged and their visitors are told the feature is unavailable.\n\nThe code works for 30 minutes and for five wrong tries. After that, save the address again and a new code is\nemailed (not sooner than a minute after the last one). A code that is not made of digits is refused without\ncounting as a try.\n\nConfirming an address that is already confirmed answers 200 with the same state, so a retry of a request that\nwent through is harmless. Saving a different address, or the same one before it was confirmed, starts again.\n\nThis needs an API key with full access. The caller must be the person who administers the partner, or a\nWidgetic administrator.\n",
|
|
18247
|
+
"tags": [
|
|
18248
|
+
"Partner",
|
|
18249
|
+
"Partners"
|
|
18250
|
+
],
|
|
18251
|
+
"security": [
|
|
18252
|
+
{
|
|
18253
|
+
"apiKeyAuth": []
|
|
18254
|
+
}
|
|
18255
|
+
],
|
|
18256
|
+
"x-access-level": "partner",
|
|
18257
|
+
"x-visibility": "public",
|
|
18258
|
+
"parameters": [
|
|
18259
|
+
{
|
|
18260
|
+
"in": "path",
|
|
18261
|
+
"name": "partnerId",
|
|
18262
|
+
"required": true,
|
|
18263
|
+
"schema": {
|
|
18264
|
+
"type": "string",
|
|
18265
|
+
"format": "uuid"
|
|
18266
|
+
},
|
|
18267
|
+
"description": "The partner that keeps the address"
|
|
18268
|
+
},
|
|
18269
|
+
{
|
|
18270
|
+
"in": "path",
|
|
18271
|
+
"name": "adapterId",
|
|
18272
|
+
"required": true,
|
|
18273
|
+
"schema": {
|
|
18274
|
+
"type": "string",
|
|
18275
|
+
"maxLength": 40
|
|
18276
|
+
},
|
|
18277
|
+
"description": "The adapter the address is for"
|
|
18278
|
+
},
|
|
18279
|
+
{
|
|
18280
|
+
"in": "path",
|
|
18281
|
+
"name": "credentialKey",
|
|
18282
|
+
"required": true,
|
|
18283
|
+
"schema": {
|
|
18284
|
+
"type": "string",
|
|
18285
|
+
"maxLength": 40
|
|
18286
|
+
},
|
|
18287
|
+
"description": "The credential's name within the adapter"
|
|
18288
|
+
}
|
|
18289
|
+
],
|
|
18290
|
+
"requestBody": {
|
|
18291
|
+
"required": true,
|
|
18292
|
+
"content": {
|
|
18293
|
+
"application/json": {
|
|
18294
|
+
"schema": {
|
|
18295
|
+
"$ref": "#/components/schemas/ConfirmAdapterConnectionRequest"
|
|
18296
|
+
}
|
|
18297
|
+
}
|
|
18298
|
+
}
|
|
18299
|
+
},
|
|
18300
|
+
"responses": {
|
|
18301
|
+
"200": {
|
|
18302
|
+
"description": "The address is confirmed (or was already)",
|
|
18303
|
+
"content": {
|
|
18304
|
+
"application/json": {
|
|
18305
|
+
"schema": {
|
|
18306
|
+
"type": "object",
|
|
18307
|
+
"properties": {
|
|
18308
|
+
"success": {
|
|
18309
|
+
"type": "boolean"
|
|
18310
|
+
},
|
|
18311
|
+
"data": {
|
|
18312
|
+
"$ref": "#/components/schemas/AdapterConnection"
|
|
18313
|
+
},
|
|
18314
|
+
"meta": {
|
|
18315
|
+
"$ref": "#/components/schemas/ResponseMeta"
|
|
18316
|
+
}
|
|
18317
|
+
},
|
|
18318
|
+
"required": [
|
|
18319
|
+
"success",
|
|
18320
|
+
"data"
|
|
18321
|
+
]
|
|
18322
|
+
}
|
|
18323
|
+
}
|
|
18324
|
+
}
|
|
18325
|
+
},
|
|
18326
|
+
"400": {
|
|
18327
|
+
"description": "A path value or the body is malformed. The body takes exactly one field, `code`",
|
|
18328
|
+
"content": {
|
|
18329
|
+
"application/json": {
|
|
18330
|
+
"schema": {
|
|
18331
|
+
"$ref": "#/components/schemas/ErrorResponse"
|
|
18332
|
+
}
|
|
18333
|
+
}
|
|
18334
|
+
}
|
|
18335
|
+
},
|
|
18336
|
+
"401": {
|
|
18337
|
+
"description": "The API key is missing or invalid",
|
|
18338
|
+
"content": {
|
|
18339
|
+
"application/json": {
|
|
18340
|
+
"schema": {
|
|
18341
|
+
"$ref": "#/components/schemas/ErrorResponse"
|
|
18342
|
+
}
|
|
18343
|
+
}
|
|
18344
|
+
}
|
|
18345
|
+
},
|
|
18346
|
+
"403": {
|
|
18347
|
+
"description": "The caller does not administer this partner, or the API key has not full access",
|
|
18348
|
+
"content": {
|
|
18349
|
+
"application/json": {
|
|
18350
|
+
"schema": {
|
|
18351
|
+
"$ref": "#/components/schemas/ErrorResponse"
|
|
18352
|
+
}
|
|
18353
|
+
}
|
|
18354
|
+
}
|
|
18355
|
+
},
|
|
18356
|
+
"404": {
|
|
18357
|
+
"description": "There is no such adapter or credential, a partner may not keep it, the credential needs no confirmation, or nothing is connected under that name (ADAPTER_NOT_FOUND, CREDENTIAL_NOT_FOUND, CREDENTIAL_NOT_FOR_THIS_ACCOUNT, CONFIRMATION_NOT_NEEDED, CREDENTIAL_NOT_CONNECTED)",
|
|
18358
|
+
"content": {
|
|
18359
|
+
"application/json": {
|
|
18360
|
+
"schema": {
|
|
18361
|
+
"$ref": "#/components/schemas/ErrorResponse"
|
|
18362
|
+
}
|
|
18363
|
+
}
|
|
18364
|
+
}
|
|
18365
|
+
},
|
|
18366
|
+
"409": {
|
|
18367
|
+
"description": "No code is waiting for the address (CONFIRMATION_NO_CODE_WAITING), or another attempt is being checked, or the address was saved again while this one was checked (CONFIRMATION_BUSY). Save the address again, or retry",
|
|
18368
|
+
"content": {
|
|
18369
|
+
"application/json": {
|
|
18370
|
+
"schema": {
|
|
18371
|
+
"$ref": "#/components/schemas/ErrorResponse"
|
|
18372
|
+
}
|
|
18373
|
+
}
|
|
18374
|
+
}
|
|
18375
|
+
},
|
|
18376
|
+
"422": {
|
|
18377
|
+
"description": "The code is not made of digits (CONFIRMATION_CODE_INVALID), is not the one emailed (CONFIRMATION_CODE_WRONG; it counts as a try) or is too old (CONFIRMATION_CODE_EXPIRED)",
|
|
18378
|
+
"content": {
|
|
18379
|
+
"application/json": {
|
|
18380
|
+
"schema": {
|
|
18381
|
+
"$ref": "#/components/schemas/ErrorResponse"
|
|
18382
|
+
}
|
|
18383
|
+
}
|
|
18384
|
+
}
|
|
18385
|
+
},
|
|
18386
|
+
"429": {
|
|
18387
|
+
"description": "Too many changes in a short time (try again after the Retry-After seconds), or five wrong codes were given and the code is dead (CONFIRMATION_TOO_MANY_ATTEMPTS): save the address again for a new one",
|
|
18388
|
+
"content": {
|
|
18389
|
+
"application/json": {
|
|
18390
|
+
"schema": {
|
|
18391
|
+
"$ref": "#/components/schemas/ErrorResponse"
|
|
18392
|
+
}
|
|
18393
|
+
}
|
|
18394
|
+
}
|
|
18395
|
+
},
|
|
18396
|
+
"503": {
|
|
18397
|
+
"description": "Adapter keys cannot be changed on this server right now (ADAPTER_CONNECTIONS_UNAVAILABLE). Nothing was changed",
|
|
18398
|
+
"content": {
|
|
18399
|
+
"application/json": {
|
|
18400
|
+
"schema": {
|
|
18401
|
+
"$ref": "#/components/schemas/ErrorResponse"
|
|
18402
|
+
}
|
|
18403
|
+
}
|
|
18404
|
+
}
|
|
18405
|
+
}
|
|
18406
|
+
},
|
|
18407
|
+
"x-code-samples": [
|
|
18408
|
+
{
|
|
18409
|
+
"lang": "TypeScript",
|
|
18410
|
+
"label": "TypeScript SDK",
|
|
18411
|
+
"source": "import { Configuration, PartnersApi } from '@widgetic/api-sdk-ts';\n\nconst partnersApi = new PartnersApi(new Configuration({ apiKey: 'YOUR_API_KEY' }));\n\n// After setPartnerAdapterConnection emailed a code to the address:\nconst connection = await partnersApi.confirmPartnerAdapterConnection({\n partnerId,\n adapterId: 'email',\n credentialKey: 'recipient',\n confirmAdapterConnectionRequest: { code: '123456' },\n});\nconsole.log(connection.awaitingConfirmation, connection.confirmedAt);\n"
|
|
18412
|
+
}
|
|
18413
|
+
]
|
|
18414
|
+
}
|
|
17860
18415
|
}
|
|
17861
18416
|
},
|
|
17862
18417
|
"components": {
|
|
@@ -17965,10 +18520,10 @@
|
|
|
17965
18520
|
},
|
|
17966
18521
|
"PublicWorkflowEventsRequest": {
|
|
17967
18522
|
"type": "object",
|
|
18523
|
+
"description": "One report from a visitor's browser: counts (`events`), the heights steps settled at (`heights`), or both. A report\nwith neither is refused.\n",
|
|
17968
18524
|
"required": [
|
|
17969
18525
|
"versionId",
|
|
17970
|
-
"token"
|
|
17971
|
-
"events"
|
|
18526
|
+
"token"
|
|
17972
18527
|
],
|
|
17973
18528
|
"properties": {
|
|
17974
18529
|
"versionId": {
|
|
@@ -17981,8 +18536,8 @@
|
|
|
17981
18536
|
},
|
|
17982
18537
|
"events": {
|
|
17983
18538
|
"type": "array",
|
|
17984
|
-
"minItems": 1,
|
|
17985
18539
|
"maxItems": 100,
|
|
18540
|
+
"description": "The counts of what visitors did. At least one of `events` and `heights` is needed.",
|
|
17986
18541
|
"items": {
|
|
17987
18542
|
"type": "object",
|
|
17988
18543
|
"required": [
|
|
@@ -18012,12 +18567,38 @@
|
|
|
18012
18567
|
}
|
|
18013
18568
|
}
|
|
18014
18569
|
}
|
|
18570
|
+
},
|
|
18571
|
+
"heights": {
|
|
18572
|
+
"type": "array",
|
|
18573
|
+
"maxItems": 10,
|
|
18574
|
+
"description": "How tall steps of this version settled in the visitor's browser, so that the embed code of the workflow can\nstart its box at the height visitors saw instead of a guess. The Embed SDK sends one for a visitor who has no\nremembered height for the step. The gateway keeps the latest few for each composition (the median is what the\ncode gets); a composition that this version does not show is left out. At least one of `events` and `heights`\nis needed.\n",
|
|
18575
|
+
"items": {
|
|
18576
|
+
"type": "object",
|
|
18577
|
+
"required": [
|
|
18578
|
+
"compositionId",
|
|
18579
|
+
"height"
|
|
18580
|
+
],
|
|
18581
|
+
"properties": {
|
|
18582
|
+
"compositionId": {
|
|
18583
|
+
"type": "string",
|
|
18584
|
+
"format": "uuid",
|
|
18585
|
+
"description": "The composition the step shows."
|
|
18586
|
+
},
|
|
18587
|
+
"height": {
|
|
18588
|
+
"type": "integer",
|
|
18589
|
+
"minimum": 1,
|
|
18590
|
+
"maximum": 100000,
|
|
18591
|
+
"description": "The height the step settled at, in pixels. One under 100 is not kept, one over 2000 is kept as 2000."
|
|
18592
|
+
}
|
|
18593
|
+
}
|
|
18594
|
+
}
|
|
18015
18595
|
}
|
|
18016
18596
|
},
|
|
18017
18597
|
"example": {
|
|
18018
18598
|
"versionId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
|
|
18019
18599
|
"token": "Example token",
|
|
18020
|
-
"events": []
|
|
18600
|
+
"events": [],
|
|
18601
|
+
"heights": []
|
|
18021
18602
|
}
|
|
18022
18603
|
},
|
|
18023
18604
|
"PublicWorkflowEventsAccepted": {
|
|
@@ -18028,15 +18609,15 @@
|
|
|
18028
18609
|
"properties": {
|
|
18029
18610
|
"recorded": {
|
|
18030
18611
|
"type": "boolean",
|
|
18031
|
-
"description": "False when nothing was counted (the workflow is not live any more, or the ids are not in that version)."
|
|
18612
|
+
"description": "False when nothing was counted or kept (the workflow is not live any more, or the ids are not in that version)."
|
|
18032
18613
|
},
|
|
18033
18614
|
"counters": {
|
|
18034
18615
|
"type": "integer",
|
|
18035
|
-
"description": "How many counters were raised."
|
|
18616
|
+
"description": "How many counters were raised (0 for a report of heights alone)."
|
|
18036
18617
|
},
|
|
18037
18618
|
"reason": {
|
|
18038
18619
|
"type": "string",
|
|
18039
|
-
"description": "Why nothing was counted, when `recorded` is false."
|
|
18620
|
+
"description": "Why nothing was counted or kept, when `recorded` is false."
|
|
18040
18621
|
}
|
|
18041
18622
|
},
|
|
18042
18623
|
"example": {
|
|
@@ -24381,7 +24962,10 @@
|
|
|
24381
24962
|
"label",
|
|
24382
24963
|
"scope",
|
|
24383
24964
|
"connected",
|
|
24384
|
-
"updatedAt"
|
|
24965
|
+
"updatedAt",
|
|
24966
|
+
"confirmation",
|
|
24967
|
+
"awaitingConfirmation",
|
|
24968
|
+
"confirmedAt"
|
|
24385
24969
|
],
|
|
24386
24970
|
"properties": {
|
|
24387
24971
|
"adapterId": {
|
|
@@ -24422,6 +25006,22 @@
|
|
|
24422
25006
|
"format": "date-time",
|
|
24423
25007
|
"nullable": true,
|
|
24424
25008
|
"description": "When the key was last set. Null when it is not connected"
|
|
25009
|
+
},
|
|
25010
|
+
"confirmation": {
|
|
25011
|
+
"type": "string",
|
|
25012
|
+
"nullable": true,
|
|
25013
|
+
"description": "How this credential is proved before it is used. `email_code` means it is an email address: saving it emails a code to it, and it is used only after the code is given back (`confirmUserAdapterConnection`, `confirmPartnerAdapterConnection`). Null for a credential that is used as soon as it is saved",
|
|
25014
|
+
"example": "email_code"
|
|
25015
|
+
},
|
|
25016
|
+
"awaitingConfirmation": {
|
|
25017
|
+
"type": "boolean",
|
|
25018
|
+
"description": "True when the credential is connected but has not been confirmed yet, so no adapter uses it. Always false when `confirmation` is null or the credential is not connected"
|
|
25019
|
+
},
|
|
25020
|
+
"confirmedAt": {
|
|
25021
|
+
"type": "string",
|
|
25022
|
+
"format": "date-time",
|
|
25023
|
+
"nullable": true,
|
|
25024
|
+
"description": "When the credential was confirmed. Null when it is not connected, is awaiting its code, or needs no confirmation"
|
|
24425
25025
|
}
|
|
24426
25026
|
},
|
|
24427
25027
|
"example": {
|
|
@@ -24431,7 +25031,10 @@
|
|
|
24431
25031
|
"label": "Resend API key",
|
|
24432
25032
|
"scope": "Example scope",
|
|
24433
25033
|
"connected": true,
|
|
24434
|
-
"updatedAt": "2026-01-15T09:30:00.000Z"
|
|
25034
|
+
"updatedAt": "2026-01-15T09:30:00.000Z",
|
|
25035
|
+
"confirmation": "email_code",
|
|
25036
|
+
"awaitingConfirmation": true,
|
|
25037
|
+
"confirmedAt": "2026-01-15T09:30:00.000Z"
|
|
24435
25038
|
}
|
|
24436
25039
|
},
|
|
24437
25040
|
"SetAdapterConnectionRequest": {
|
|
@@ -24446,7 +25049,7 @@
|
|
|
24446
25049
|
"format": "password",
|
|
24447
25050
|
"writeOnly": true,
|
|
24448
25051
|
"maxLength": 2048,
|
|
24449
|
-
"description": "The key exactly as its provider gave it: one line of text, at most 2048 characters. It is stored encrypted and is never returned or logged.",
|
|
25052
|
+
"description": "The key exactly as its provider gave it: one line of text, at most 2048 characters. It is stored encrypted and is never returned or logged. For a credential that is an email address (`confirmation: email_code`), write that one address, with nothing else",
|
|
24450
25053
|
"example": "YOUR_PROVIDER_KEY"
|
|
24451
25054
|
}
|
|
24452
25055
|
},
|
|
@@ -24454,6 +25057,24 @@
|
|
|
24454
25057
|
"credential": "YOUR_PROVIDER_KEY"
|
|
24455
25058
|
}
|
|
24456
25059
|
},
|
|
25060
|
+
"ConfirmAdapterConnectionRequest": {
|
|
25061
|
+
"type": "object",
|
|
25062
|
+
"required": [
|
|
25063
|
+
"code"
|
|
25064
|
+
],
|
|
25065
|
+
"additionalProperties": false,
|
|
25066
|
+
"properties": {
|
|
25067
|
+
"code": {
|
|
25068
|
+
"type": "string",
|
|
25069
|
+
"maxLength": 32,
|
|
25070
|
+
"description": "The digits of the code Widgetic emailed to the address, with nothing else. It works for 30 minutes and for five wrong tries; after that, save the address again and a new code is emailed",
|
|
25071
|
+
"example": "123456"
|
|
25072
|
+
}
|
|
25073
|
+
},
|
|
25074
|
+
"example": {
|
|
25075
|
+
"code": "123456"
|
|
25076
|
+
}
|
|
25077
|
+
},
|
|
24457
25078
|
"AdapterConnectionRemoval": {
|
|
24458
25079
|
"type": "object",
|
|
24459
25080
|
"required": [
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@widgetic/api-contracts",
|
|
3
|
-
"version": "1.11.
|
|
3
|
+
"version": "1.11.109",
|
|
4
4
|
"description": "What the Widgetic API and the Widgetic MCP server accept, as data: the public OpenAPI description and the MCP tool contract. Written by the Widgetic API gateway; the Widgetic CLI is generated from it.",
|
|
5
5
|
"author": "Widgetic",
|
|
6
6
|
"license": "SEE LICENSE IN LICENSE",
|