# Stoplight Elements > Work with API documentation built on Stoplight Elements, Stoplight's open-source toolkit for interactive API docs. Read any public Stoplight project the way Elements Dev Portal does: its versions, every page in its sidebar, one article, API, endpoint or model in full, and a search of everything it says. Save an API's OpenAPI document as a file, and call its hosted mock server to see what the API would answer. Build standalone pages with Elements - an API reference from any OpenAPI document, or a whole developer portal from a Stoplight project - to host anywhere. No account or API key required. App · Utilities · 8 actions. Web page: https://docs.lodol.com/docs/integrations/stoplight-elements ## Actions ### Call a mock server Send a request to an endpoint's hosted mock server - Stoplight's Prism, answering from the API's own docs - and get back what the API would answer: the status, headers and body, before the API itself exists or without touching it. Fills in whatever the step leaves out from the endpoint's examples, and a stand-in credential where one is needed, which the result lists. Ask for a documented status code, a named example or freshly generated data, as Try It's mocking menu does. No account or API key required. **Inputs** - Project (`project`, text, required): A public Stoplight project: its ID from the project's settings, such as 'cHJqOjYwNjYx' (Stoplight's Studio Demo); its workspace and project as 'elements-examples/studio-demo'; or the address of its docs, such as https://elements-examples.stoplight.io/docs/studio-demo, on stoplight.io or the docs' own domain. - Endpoint (`endpoint`, text, required): The endpoint's page: its slug, such as 'b3A6Mzg5NDM1-list-todos', its ID, or its address in the docs. List them with 'List a project's pages' and Kind of page set to Endpoint. - Branch (`branch`, text): Optional. The version of the docs to read, by its branch's slug, such as 'v2'. The project's default branch when blank. - Path parameters (`path_params`, object): Optional. Values for the parameters in the endpoint's path, by name, such as todoId. Each one left out is given the docs' example. - Query values (`query`, object): Optional. Values to add to the end of the address, by name. A required one left out is given the docs' example. - Headers (`headers`, object): Optional. Headers to send, by name - a credential of your own, for one. Any value will do for a mock. - Body (`body`, object): Optional. The request body, as field names and values. The docs' example of it when left out, or a small one its schema accepts. - Answer with status (`response_code`, text): Optional. The documented response to answer with, by its status code, such as 404. The endpoint's lowest success code by default, as the mock server picks. - Example (`example`, text): Optional. The documented example to answer with, by its name, such as 'List of Todos'. Chain it from 'example_names' in 'Get a page'. - Generate data (`dynamic`, true/false): Optional. Answer with fresh random data that fits the schema, rather than the docs' examples. A named example still wins. Default: `false`. **Outputs** - `body` (object): The answer's body: its JSON, parsed - an object or a list - or its text. - `content_type` (text): The answer's media type. - `credentials_added` (list): The stand-in credentials sent because the endpoint needs one and the step set none. Empty otherwise. - `endpoint` (text): The slug of the endpoint's page. - `headers` (object): The answer's headers, with names in lower case. - `method` (text): The HTTP method the request was sent with. - `mock_server_url` (text): The mock server's address. - `ok` (true/false): True for a 2xx answer. - `path` (text): The path it was sent to, with its parameters filled in. - `prefer` (text): The Prefer header sent to choose the answer, e.g. 'code=404'. Null when none was. - `project_id` (text): The project's ID, as Elements Dev Portal takes it - chain it into the next step's Project field. - `request_body` (object): The body that was sent. Null when none was. - `status` (number): The status code the mock answered with. - `title` (text): The endpoint's title. - `url` (text): The full address it was sent to. - `violations` (list): What the mock found wrong with the request or its own answer, measured against the docs, when it answered anyway. **Example output** ```json { "body": { "completed": true, "completed_at": "2019-08-24T14:15:22Z", "created_at": "2019-08-24T14:15:22Z", "id": 0, "name": "string", "updated_at": "2019-08-24T14:15:22Z" }, "content_type": "application/json", "credentials_added": [], "endpoint": "b3A6Mzg5NDM4-get-todo", "headers": { "content-type": "application/json" }, "method": "GET", "mock_server_url": "https://stoplight.io/mocks/elements-examples/studio-demo/389434", "ok": true, "path": "/todos/1", "prefer": null, "project_id": "cHJqOjYwNjYx", "request_body": null, "status": 200, "title": "Get Todo", "url": "https://stoplight.io/mocks/elements-examples/studio-demo/389434/todos/1", "violations": [] } ``` ### Create a developer portal page Build a standalone web page that renders a whole public Stoplight project with Elements Dev Portal - its articles and guides, every API, endpoint and model, the version picker, Try It and the hosted mock servers - ready to upload to any static host or embed in a site. The page reads the project live from Stoplight each time it is opened, so it stays current. Stoplight lets anyone use the Dev Portal while developing on their own machine; serving it from a live site needs the project's workspace on a paid Stoplight plan. No account or API key required to build it. **Inputs** - Project (`project`, text, required): A public Stoplight project: its ID from the project's settings, such as 'cHJqOjYwNjYx' (Stoplight's Studio Demo); its workspace and project as 'elements-examples/studio-demo'; or the address of its docs, such as https://elements-examples.stoplight.io/docs/studio-demo, on stoplight.io or the docs' own domain. - Page title (`title`, text): Optional. The title in the browser tab. The project's name by default. - Collapse the contents (`collapse_table_of_contents`, true/false): Optional. Start with the sidebar's folders closed, for a project with many pages. Default: `false`. - Hide Try It (`hide_try_it`, true/false): Optional. Leave out the Try It console that sends requests from the docs, for docs that should only be read. Default: `false`. - Hide mocking (`hide_mocking`, true/false): Optional. Leave out the mock servers and every mention of them. Default: `false`. - Hide the Export button (`hide_export`, true/false): Optional. Leave out the button that downloads the API's document. Default: `false`. - Hide server addresses (`hide_server_info`, true/false): Optional. Leave out the list of servers the API is called on. Default: `false`. - Hide security (`hide_security_info`, true/false): Optional. Leave out how the API is authenticated. Default: `false`. - Try It CORS proxy (`try_it_cors_proxy`, text): Optional. The address of a CORS proxy to send Try It requests through, for APIs that do not let a browser call them from another site. It is put in front of each request's address. - Return as (`output`, text): An HTML file, the default, or the page's HTML as text in the result. One of: `file` (An HTML file), `text` (Text in the result). Default: `file`. - File name (`filename`, text): Optional. The name to save the file under. Made from the page title by default, e.g. 'to-dos.html'. **Outputs** - `attributes` (object): The options written on the web component, by the attribute name Elements reads, e.g. {'router': 'hash', 'hideTryIt': 'true'}. A document written into the page is left out. - `content_type` (text): The saved file's media type. - `docs_url` (text): The address of the same project's docs on Stoplight. - `document_ref` (text): The saved file's reference, to attach it to an email, upload it or store it in a later step. Null when nothing was saved. - `documents` (list): The saved file, as a one-item list. - `download_url` (text): Where Lodol serves the saved file. - `filename` (text): The name the file was saved under. - `html` (text): The page's HTML, when it was asked for as text. Null when it was saved as a file. - `output` (text): How the page came back: 'file' or 'text'. - `project_id` (text): The project's ID, as Elements Dev Portal takes it - chain it into the next step's Project field. - `project_name` (text): The project's name. - `size_bytes` (number): The page's size in bytes. - `title` (text): The page's title. **Example output** ```json { "attributes": { "projectId": "cHJqOjYwNjYx", "router": "hash" }, "content_type": "text/html", "docs_url": "https://elements-examples.stoplight.io/docs/studio-demo", "document_ref": "doc_stoplight_elements_studio_demo_html", "documents": [ { "content_type": "text/html", "document_ref": "doc_stoplight_elements_studio_demo_html", "filename": "studio-demo.html", "size_bytes": 696, "url": "/actions/core/serve-document/doc_stoplight_elements_studio_demo_html?teamId=65f0c0ffee0000000000c0de" } ], "download_url": "/actions/core/serve-document/doc_stoplight_elements_studio_demo_html?teamId=65f0c0ffee0000000000c0de", "filename": "studio-demo.html", "html": null, "output": "file", "project_id": "cHJqOjYwNjYx", "project_name": "Studio Demo", "size_bytes": 696, "title": "Studio Demo" } ``` ### Create an API reference page Build a standalone web page that renders an OpenAPI document as Stoplight Elements' interactive API reference - a sidebar of endpoints and models, request samples and a Try It console - ready to upload to any static host, attach to an email or publish from a later step. Pick the layout, a title and a logo, and which parts to leave out. A document given by address is loaded fresh each time the page is opened; one given as a file or text is written into the page. Nothing is sent anywhere to build it. No account or API key required. **Inputs** - API document (`document`, text, required): The OpenAPI 3 or Swagger 2.0 document, in JSON or YAML: upload the file, paste its text, use a file or document from an earlier step, or give its public address, which browsers must be allowed to fetch (GitHub's raw addresses are). - Page title (`title`, text): Optional. The title in the browser tab. The API's own title for a document given as a file or text, otherwise 'API Reference'. - Layout (`layout`, text): Sidebar, the default, with the contents on the left; Responsive, which folds the sidebar away on small screens; or Stacked, one column, for a page with a sidebar of its own. One of: `sidebar`, `responsive`, `stacked`. Default: `sidebar`. - Logo (`logo`, text): Optional. The address of a square image to show beside the API's title, above the contents. - Hide Try It (`hide_try_it`, true/false): Optional. Leave out the Try It console that sends requests from the docs, for docs that should only be read. Default: `false`. - Hide the Try It panel (`hide_try_it_panel`, true/false): Optional. Leave out the Try It panel but keep the request samples. Default: `false`. - Hide request samples (`hide_samples`, true/false): Optional. Leave out the code samples for each request. Default: `false`. - Hide models (`hide_schemas`, true/false): Optional. Leave the models out of the sidebar. Default: `false`. - Hide internal (`hide_internal`, true/false): Optional. Leave out the endpoints and models the document marks x-internal. Default: `false`. - Hide the Export button (`hide_export`, true/false): Optional. Leave out the button that downloads the API's document. Default: `false`. - Hide server addresses (`hide_server_info`, true/false): Optional. Leave out the list of servers the API is called on. Default: `false`. - Hide security (`hide_security_info`, true/false): Optional. Leave out how the API is authenticated. Default: `false`. - Try It CORS proxy (`try_it_cors_proxy`, text): Optional. The address of a CORS proxy to send Try It requests through, for APIs that do not let a browser call them from another site. It is put in front of each request's address. - Return as (`output`, text): An HTML file, the default, or the page's HTML as text in the result. One of: `file` (An HTML file), `text` (Text in the result). Default: `file`. - File name (`filename`, text): Optional. The name to save the file under. Made from the page title by default, e.g. 'to-dos.html'. **Outputs** - `attributes` (object): The options written on the web component, by the attribute name Elements reads, e.g. {'router': 'hash', 'hideTryIt': 'true'}. A document written into the page is left out. - `content_type` (text): The saved file's media type. - `document_ref` (text): The saved file's reference, to attach it to an email, upload it or store it in a later step. Null when nothing was saved. - `document_url` (text): The address the page loads the document from. Null when the document is written into the page. - `documents` (list): The saved file, as a one-item list. - `download_url` (text): Where Lodol serves the saved file. - `embedded` (true/false): True when the document is written into the page, so the page works on its own. - `filename` (text): The name the file was saved under. - `html` (text): The page's HTML, when it was asked for as text. Null when it was saved as a file. - `layout` (text): Its layout: 'sidebar', 'responsive' or 'stacked'. - `output` (text): How the page came back: 'file' or 'text'. - `size_bytes` (number): The page's size in bytes. - `title` (text): The page's title. **Example output** ```json { "attributes": { "hideTryIt": "true", "layout": "sidebar", "router": "hash" }, "content_type": "text/html", "document_ref": "doc_stoplight_elements_to_dos_html", "document_url": null, "documents": [ { "content_type": "text/html", "document_ref": "doc_stoplight_elements_to_dos_html", "filename": "to-dos.html", "size_bytes": 13673, "url": "/actions/core/serve-document/doc_stoplight_elements_to_dos_html?teamId=65f0c0ffee0000000000c0de" } ], "download_url": "/actions/core/serve-document/doc_stoplight_elements_to_dos_html?teamId=65f0c0ffee0000000000c0de", "embedded": true, "filename": "to-dos.html", "html": null, "layout": "sidebar", "output": "file", "size_bytes": 13673, "title": "To-dos" } ``` ### Get a page Read one page of a public Stoplight project's docs, as Elements Dev Portal shows it: an article's Markdown; an API's version, servers and security; an endpoint's method and path, parameters, request body and every response with its schema and examples; or a model's JSON Schema. Comes with the pages it links to, its mock server's address and its Export links. Name it by its slug, its ID or its address in the docs. The detail to hand an AI step writing a client, a test or a summary. No account or API key required. **Inputs** - Project (`project`, text, required): A public Stoplight project: its ID from the project's settings, such as 'cHJqOjYwNjYx' (Stoplight's Studio Demo); its workspace and project as 'elements-examples/studio-demo'; or the address of its docs, such as https://elements-examples.stoplight.io/docs/studio-demo, on stoplight.io or the docs' own domain. - Page (`page`, text, required): The page: its slug, such as 'b3A6Mzg5NDM2-create-todo', its ID, or its address in the docs. Chain it from 'page_slugs' in 'List a project's pages'. - Branch (`branch`, text): Optional. The version of the docs to read, by its branch's slug, such as 'v2'. The project's default branch when blank. **Outputs** - `branch` (text): The branch it was read from. - `data` (object): The page's content exactly as Stoplight stores it: an API, endpoint or model in the form Elements renders. Null for an article, whose text is in 'markdown'. - `description` (text): An API's, endpoint's or model's description, often Markdown. Null for an article. - `docs_url` (text): Where the project's hosted docs show it. - `export_bundled_url` (text): Where it downloads the same file with its references to other files bundled in. - `export_url` (text): Where the Export button downloads an API's or a model's file as it is. Null for other pages. - `id` (text): The page's ID, the start of its slug. - `markdown` (text): An article's text, in Markdown. Null for other pages. - `method` (text): An endpoint's or webhook's HTTP method, e.g. 'POST'. Null for other pages. - `mock_server_url` (text): The address of the API's hosted mock server, for an API or an endpoint. Null when it has none. - `parameters` (list): An endpoint's path, query, header and cookie parameters. - `path` (text): An endpoint's path, with its parameters in braces, or a webhook's name. Null for other pages. - `project_id` (text): The project's ID, as Elements Dev Portal takes it - chain it into the next step's Project field. - `related` (list): The pages it links to, such as the API an endpoint belongs to and the models it uses. - `request_body` (object): What an endpoint takes in its body. Null when it takes nothing. - `responses` (list): Every response an endpoint documents, in order. - `schema` (object): A model's JSON Schema. Null for other pages. - `security` (list): The names of the ways it is authenticated, e.g. 'API Key'. Empty when it needs no credentials. - `servers` (list): The addresses an API or endpoint is called on. - `slug` (text): The page's slug: its ID and its title, as the docs' address ends - chain it into 'Get a page'. - `summary` (text): Its summary, on one line or a few. - `title` (text): The page's title, as the sidebar shows it. - `type` (text): What kind of page it is: 'article', 'http_service' (an API), 'http_operation' (an endpoint), 'http_webhook' or 'model'. - `type_label` (text): The kind of page as the docs call it: 'Article', 'API', 'Endpoint', 'Webhook' or 'Model'. - `uri` (text): The file it comes from in the project, and where in it, e.g. '/reference/todos.yaml/paths/~1todos/post'. - `version` (text): An API's version. Null for other pages. **Example output** ```json { "branch": "master", "data": { "description": "This creates a Todo object\n\n*Markdown is supported in descriptions. Add information here for users to get accustomed to endpoints*", "extensions": {}, "id": "3fb12610e1ab0", "iid": "post-todos", "method": "post", "path": "/todos", "request": { "body": { "contents": [ { "encodings": [], "examples": [], "id": "770b4257ecc56", "mediaType": "application/json", "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "description": "I'm a model's description.", "properties": { "completed": { "default": false, "description": "Boolean indicating if the task has been completed or not", "type": "boolean" }, "completed_at": { "description": "Time when the task was completed", "format": "date-time", "readOnly": true, "type": "string" }, "created_at": { "description": "Time when the task was created", "format": "date-time", "readOnly": true, "type": "string" }, "id": { "description": "ID of the task", "maximum": 9999, "minimum": 0, "readOnly": true, "type": "number" }, "name": { "description": "Name of the task", "maxLength": 100, "minLength": 1, "type": "string" }, "updated_at": { "description": "Time when the task was updated", "format": "date-time", "readOnly": true, "type": "string" } }, "required": [ "id", "name", "completed_at", "created_at", "updated_at" ], "title": "Todo", "type": "object", "x-examples": {}, "x-stoplight": { "id": "246e949b07b91" } } } ], "description": "Name of the Todo", "id": "53501f245b1c7" }, "cookie": [], "headers": [ { "description": "application/json", "examples": [], "explicitProperties": [ "name", "in", "required", "schema", "description" ], "id": "a17bd1f8180e1", "name": "Content-Type", "required": true, "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "default": "application/json", "type": "string", "x-stoplight": { "id": "0f3e124740ff1" } }, "style": "simple" } ], "path": [], "query": [] }, "responses": [ { "code": "201", "contents": [ { "encodings": [], "examples": [ { "id": "d1da513e845f2", "key": "Example Todo", "value": { "completed": true, "completed_at": "2019-08-24T14:15:22Z", "created_at": "2019-08-24T14:15:22Z", "id": 0, "name": "string", "updated_at": "2019-08-24T14:15:22Z" } } ], "id": "739ee9894633b", "mediaType": "multipart/form-data", "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "description": "I'm a model's description.", "properties": { "completed": { "default": false, "description": "Boolean indicating if the task has been completed or not", "type": "boolean" }, "completed_at": { "description": "Time when the task was completed", "format": "date-time", "readOnly": true, "type": "string" }, "created_at": { "description": "Time when the task was created", "format": "date-time", "readOnly": true, "type": "string" }, "id": { "description": "ID of the task", "maximum": 9999, "minimum": 0, "readOnly": true, "type": "number" }, "name": { "description": "Name of the task", "maxLength": 100, "minLength": 1, "type": "string" }, "updated_at": { "description": "Time when the task was updated", "format": "date-time", "readOnly": true, "type": "string" } }, "required": [ "id", "name", "completed_at", "created_at", "updated_at" ], "title": "Todo", "type": "object", "x-examples": {}, "x-stoplight": { "id": "246e949b07b91" } } } ], "description": "New Todo Created", "headers": [], "id": "b1bc2d941bf4d" }, { "code": "403", "contents": [ { "encodings": [], "examples": [], "id": "2ca41b032e737", "mediaType": "application/json", "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object", "x-stoplight": { "id": "4d837350d9677" } } } ], "description": "Action not allowed", "headers": [], "id": "2b4baae352bdb" }, { "code": "404", "contents": [ { "encodings": [], "examples": [], "id": "e687356a30b3f", "mediaType": "application/json", "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "description": "A standard error object.", "properties": { "error": { "type": "string" }, "status": { "description": "A code.", "type": "string" } }, "required": [ "status", "error" ], "title": "Error", "type": "object", "x-stoplight": { "id": "b4ff2c170dab2" }, "x-tags": [ "Common" ] } } ], "description": "Resource not found", "headers": [], "id": "e1ec81895f49e" } ], "security": [ [ { "description": "Just use `123`. It's super secure ;)", "extensions": {}, "id": "de1755561948a", "in": "query", "key": "API Key", "name": "apikey", "type": "apiKey" } ] ], "securityDeclarationType": "declared", "servers": [ { "description": "Production", "id": "a43be97b14e11", "name": "To-dos", "url": "https://todos.stoplight.io" }, { "description": "Sandbox", "id": "18b5b15918af5", "name": "To-dos", "url": "https://todos-sandbox.stoplight.io" } ], "summary": "Create Todo", "tags": [] }, "description": "This creates a Todo object\n\n*Markdown is supported in descriptions. Add information here for users to get accustomed to endpoints*", "docs_url": "https://elements-examples.stoplight.io/docs/studio-demo/b3A6Mzg5NDM2-create-todo", "export_bundled_url": null, "export_url": null, "id": "b3A6Mzg5NDM2", "markdown": null, "method": "POST", "mock_server_url": "https://stoplight.io/mocks/elements-examples/studio-demo/389434", "parameters": [ { "description": "application/json", "example": "application/json", "in": "header", "name": "Content-Type", "required": true, "type": "string" } ], "path": "/todos", "project_id": "cHJqOjYwNjYx", "related": [], "request_body": { "content_types": [ "application/json" ], "description": "Name of the Todo", "example": null, "required": false, "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "description": "I'm a model's description.", "properties": { "completed": { "default": false, "description": "Boolean indicating if the task has been completed or not", "type": "boolean" }, "completed_at": { "description": "Time when the task was completed", "format": "date-time", "readOnly": true, "type": "string" }, "created_at": { "description": "Time when the task was created", "format": "date-time", "readOnly": true, "type": "string" }, "id": { "description": "ID of the task", "maximum": 9999, "minimum": 0, "readOnly": true, "type": "number" }, "name": { "description": "Name of the task", "maxLength": 100, "minLength": 1, "type": "string" }, "updated_at": { "description": "Time when the task was updated", "format": "date-time", "readOnly": true, "type": "string" } }, "required": [ "id", "name", "completed_at", "created_at", "updated_at" ], "title": "Todo", "type": "object", "x-examples": {}, "x-stoplight": { "id": "246e949b07b91" } } }, "responses": [ { "content_types": [ "multipart/form-data" ], "description": "New Todo Created", "example_names": [ "Example Todo" ], "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "description": "I'm a model's description.", "properties": { "completed": { "default": false, "description": "Boolean indicating if the task has been completed or not", "type": "boolean" }, "completed_at": { "description": "Time when the task was completed", "format": "date-time", "readOnly": true, "type": "string" }, "created_at": { "description": "Time when the task was created", "format": "date-time", "readOnly": true, "type": "string" }, "id": { "description": "ID of the task", "maximum": 9999, "minimum": 0, "readOnly": true, "type": "number" }, "name": { "description": "Name of the task", "maxLength": 100, "minLength": 1, "type": "string" }, "updated_at": { "description": "Time when the task was updated", "format": "date-time", "readOnly": true, "type": "string" } }, "required": [ "id", "name", "completed_at", "created_at", "updated_at" ], "title": "Todo", "type": "object", "x-examples": {}, "x-stoplight": { "id": "246e949b07b91" } }, "status": "201" }, { "content_types": [ "application/json" ], "description": "Action not allowed", "example_names": [], "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "properties": { "message": { "type": "string" } }, "required": [ "message" ], "type": "object", "x-stoplight": { "id": "4d837350d9677" } }, "status": "403" }, { "content_types": [ "application/json" ], "description": "Resource not found", "example_names": [], "schema": { "$schema": "http://json-schema.org/draft-07/schema#", "description": "A standard error object.", "properties": { "error": { "type": "string" }, "status": { "description": "A code.", "type": "string" } }, "required": [ "status", "error" ], "title": "Error", "type": "object", "x-stoplight": { "id": "b4ff2c170dab2" }, "x-tags": [ "Common" ] }, "status": "404" } ], "schema": null, "security": [ "API Key" ], "servers": [ "https://todos.stoplight.io", "https://todos-sandbox.stoplight.io" ], "slug": "b3A6Mzg5NDM2-create-todo", "summary": "This creates a Todo object\n\n*Markdown is supported in descriptions. Add information here for users to get accustomed to endpoints*", "title": "Create Todo", "type": "http_operation", "type_label": "Endpoint", "uri": "/reference/todos/todo.v1.yaml/paths/~1todos/post", "version": null } ``` ### Get a Stoplight project Look up a public Stoplight project - the thing Elements Dev Portal renders - by its ID, its workspace and name, or the address of its docs, and get back its name, its workspace, the address of its hosted docs, its ID for the steps after, and every version of its docs with the default one marked. The step to start from. No account or API key required. **Inputs** - Project (`project`, text, required): A public Stoplight project: its ID from the project's settings, such as 'cHJqOjYwNjYx' (Stoplight's Studio Demo); its workspace and project as 'elements-examples/studio-demo'; or the address of its docs, such as https://elements-examples.stoplight.io/docs/studio-demo, on stoplight.io or the docs' own domain. **Outputs** - `branch_count` (number): How many branches it has. - `branch_slugs` (list): Each branch's slug, to loop over. - `branches` (list): Every branch - each a version of the docs. - `default_branch` (text): The branch its docs show unless another is asked for. - `docs_url` (text): The address of the project's hosted docs. - `handle` (text): The project as workspace/project, e.g. 'elements-examples/studio-demo' - another way to name it. - `name` (text): The project's name. - `project_id` (text): The project's ID, as Elements Dev Portal takes it - chain it into the next step's Project field. - `slug` (text): The project's slug, as its docs' address has it. - `workspace_id` (text): The ID of the workspace it belongs to. - `workspace_name` (text): The workspace's name. - `workspace_slug` (text): The workspace's slug, the start of its docs' address on stoplight.io. **Example output** ```json { "branch_count": 1, "branch_slugs": [ "master" ], "branches": [ { "is_default": true, "is_published": true, "name": "master", "slug": "master" } ], "default_branch": "master", "docs_url": "https://elements-examples.stoplight.io/docs/studio-demo", "handle": "elements-examples/studio-demo", "name": "Studio Demo", "project_id": "cHJqOjYwNjYx", "slug": "studio-demo", "workspace_id": "d2s6NDE1NTU", "workspace_name": "elements-examples", "workspace_slug": "elements-examples" } ``` ### List a project's pages List the pages of a public Stoplight project's docs - its articles, APIs, endpoints, webhooks and models - in the order its sidebar shows them, with the divider and folders each is filed under, the API it belongs to, each endpoint's method, and its address in the docs. Narrow it to one kind of page, one API or some text, on any branch. The way to find a page's slug, build an endpoint inventory, or loop over a project. No account or API key required. **Inputs** - Project (`project`, text, required): A public Stoplight project: its ID from the project's settings, such as 'cHJqOjYwNjYx' (Stoplight's Studio Demo); its workspace and project as 'elements-examples/studio-demo'; or the address of its docs, such as https://elements-examples.stoplight.io/docs/studio-demo, on stoplight.io or the docs' own domain. - Branch (`branch`, text): Optional. The version of the docs to read, by its branch's slug, such as 'v2'. The project's default branch when blank. - Kind of page (`type`, text): Optional. Only pages of this kind. One of: `article`, `http_service` (API), `http_operation` (Endpoint), `http_webhook` (Webhook), `model`. - API (`api`, text): Optional. Only the endpoints, webhooks and models of this API, by its title, such as 'To-dos', or its slug. An API the project does not have is an error that names the ones it does. - Text to look for (`search`, text): Optional. Only pages whose title or method contains this text. Case does not matter. To search what the pages say, use 'Search a project's docs'. - Limit (`limit`, number): How many pages to return at most, from 1 to 500. 100 by default. The totals come back with them, so a cut-off is visible. From 1 to 500. Default: `100`. **Outputs** - `branch` (text): The branch that was read. Null when it was the project's default. - `count` (number): How many pages were returned. - `external_links` (list): Links out of the project that its sidebar shows. - `first` (object): The first page returned, for the step that only wanted one. Null when none matched. - `page_slugs` (list): The slug of each page returned, in order, to loop over. - `pages` (list): The pages, in the sidebar's order. - `project_id` (text): The project's ID, as Elements Dev Portal takes it - chain it into the next step's Project field. - `project_name` (text): The project's name. - `total` (number): How many pages the project has in all, before any filtering. - `total_matches` (number): How many pages matched in all, of which the ones returned are the first. - `truncated` (true/false): True when more matched than the limit allowed. - `type_counts` (object): How many pages of each kind the project has, e.g. {'article': 4, 'http_operation': 12}. **Example output** ```json { "branch": null, "count": 2, "external_links": [], "first": { "api": "To-dos", "docs_url": "https://elements-examples.stoplight.io/docs/studio-demo/b3A6Mzg5NDM1-list-todos", "groups": [], "id": "b3A6Mzg5NDM1", "method": "GET", "section": "APIS", "slug": "b3A6Mzg5NDM1-list-todos", "title": "List Todos", "type": "http_operation" }, "page_slugs": [ "b3A6Mzg5NDM1-list-todos", "b3A6Mzg5NDM2-create-todo" ], "pages": [ { "api": "To-dos", "docs_url": "https://elements-examples.stoplight.io/docs/studio-demo/b3A6Mzg5NDM1-list-todos", "groups": [], "id": "b3A6Mzg5NDM1", "method": "GET", "section": "APIS", "slug": "b3A6Mzg5NDM1-list-todos", "title": "List Todos", "type": "http_operation" }, { "api": "To-dos", "docs_url": "https://elements-examples.stoplight.io/docs/studio-demo/b3A6Mzg5NDM2-create-todo", "groups": [], "id": "b3A6Mzg5NDM2", "method": "POST", "section": "APIS", "slug": "b3A6Mzg5NDM2-create-todo", "title": "Create Todo", "type": "http_operation" } ], "project_id": "cHJqOjYwNjYx", "project_name": "Studio Demo", "total": 24, "total_matches": 9, "truncated": true, "type_counts": { "article": 4, "http_operation": 12, "http_service": 2, "model": 6 } } ``` ### Save an API's document as a file Save an API's OpenAPI document - or a model's JSON Schema - from a public Stoplight project as a file, the way the docs' Export button does: bundled, with every reference to another file copied in so it stands alone, or the original file as it is. A later step can commit it, attach it, feed it to a code generator or build an API reference page from it. No account or API key required. **Inputs** - Project (`project`, text, required): A public Stoplight project: its ID from the project's settings, such as 'cHJqOjYwNjYx' (Stoplight's Studio Demo); its workspace and project as 'elements-examples/studio-demo'; or the address of its docs, such as https://elements-examples.stoplight.io/docs/studio-demo, on stoplight.io or the docs' own domain. - API or model (`api`, text, required): The API's page - or a model's - by its slug, such as 'YXBpOjM4OTQzNA-to-dos', its ID, or its address in the docs. List them with 'List a project's pages' and Kind of page set to API. - Branch (`branch`, text): Optional. The version of the docs to read, by its branch's slug, such as 'v2'. The project's default branch when blank. - Export as (`mode`, text): Bundled, the default, copies in everything the file refers to in other files, so it stands alone; Original is the file as it is in the project. One of: `bundled`, `original`. Default: `bundled`. - File name (`filename`, text): Optional. The name to save the file under. The project's own file name by default, e.g. 'todo.v1.yaml'; a name without an extension gains the file's. **Outputs** - `api` (text): The slug of the page that was exported. - `content_type` (text): The saved file's media type. - `document_ref` (text): The saved file's reference, to attach it to an email, upload it or store it in a later step. Null when nothing was saved. - `documents` (list): The saved file, as a one-item list. - `download_url` (text): Where Lodol serves the saved file. - `filename` (text): The name the file was saved under. - `format` (text): The file's format: 'json' or 'yaml'. - `mode` (text): How it was exported: 'bundled' or 'original'. - `project_id` (text): The project's ID, as Elements Dev Portal takes it - chain it into the next step's Project field. - `size_bytes` (number): The file's size in bytes. - `title` (text): The API's or model's title. - `type` (text): What was exported: 'http_service' (an API) or 'model'. - `url` (text): The Export link it was downloaded from. **Example output** ```json { "api": "YXBpOjM4OTQzNA-to-dos", "content_type": "application/yaml", "document_ref": "doc_stoplight_elements_todo_v1_yaml", "documents": [ { "content_type": "application/yaml", "document_ref": "doc_stoplight_elements_todo_v1_yaml", "filename": "todo.v1.yaml", "size_bytes": 12135, "url": "/actions/core/serve-document/doc_stoplight_elements_todo_v1_yaml?teamId=65f0c0ffee0000000000c0de" } ], "download_url": "/actions/core/serve-document/doc_stoplight_elements_todo_v1_yaml?teamId=65f0c0ffee0000000000c0de", "filename": "todo.v1.yaml", "format": "yaml", "mode": "bundled", "project_id": "cHJqOjYwNjYx", "size_bytes": 12135, "title": "To-dos", "type": "http_service", "url": "https://stoplight.io/api/v1/projects/elements-examples/studio-demo/nodes/reference/todos/todo.v1.yaml?fromExportButton=true&snapshotType=http_service&deref=optimizedBundle" } ``` ### Search a project's docs Search everything a public Stoplight project's docs say - titles, summaries and text - the way Elements Dev Portal's search box does, and get back the matching pages with the passage that matched and each page's address. The way to find where the docs cover a topic, or to hand an AI step the right page. No account or API key required. **Inputs** - Project (`project`, text, required): A public Stoplight project: its ID from the project's settings, such as 'cHJqOjYwNjYx' (Stoplight's Studio Demo); its workspace and project as 'elements-examples/studio-demo'; or the address of its docs, such as https://elements-examples.stoplight.io/docs/studio-demo, on stoplight.io or the docs' own domain. - Search for (`query`, text, required): The words to look for, such as 'create todo'. - Branch (`branch`, text): Optional. The version of the docs to read, by its branch's slug, such as 'v2'. The project's default branch when blank. - Limit (`limit`, number): How many results to return at most, from 1 to 100. 20 by default. From 1 to 100. Default: `20`. **Outputs** - `branch` (text): The branch that was read. Null when it was the project's default. - `count` (number): How many results were returned. - `first` (object): The best match. Null when nothing matched. - `page_slugs` (list): The slug of each page returned, in order, to loop over. - `project_id` (text): The project's ID, as Elements Dev Portal takes it - chain it into the next step's Project field. - `query` (text): What was searched for. - `results` (list): The matching pages, best match first. - `total` (number): How many pages Stoplight found. - `truncated` (true/false): True when more were found than the limit allowed. **Example output** ```json { "branch": null, "count": 2, "first": { "docs_url": "https://elements-examples.stoplight.io/docs/studio-demo/b3A6Mzg5NDM2-create-todo", "id": "b3A6Mzg5NDM2", "project_name": "Studio Demo", "slug": "b3A6Mzg5NDM2-create-todo", "snippet": "This creates a Todo object *Markdown is supported in descriptions. Add information here for users to get accustomed to endpoints*", "summary": "This creates a Todo object\n\n*Markdown is supported in descriptions. Add information here for users to get accustomed to endpoints*", "title": "Create Todo", "type": "http_operation" }, "page_slugs": [ "b3A6Mzg5NDM2-create-todo", "YXBpOjM4OTQzNA-to-dos" ], "project_id": "cHJqOjYwNjYx", "query": "create todo", "results": [ { "docs_url": "https://elements-examples.stoplight.io/docs/studio-demo/b3A6Mzg5NDM2-create-todo", "id": "b3A6Mzg5NDM2", "project_name": "Studio Demo", "slug": "b3A6Mzg5NDM2-create-todo", "snippet": "This creates a Todo object *Markdown is supported in descriptions. Add information here for users to get accustomed to endpoints*", "summary": "This creates a Todo object\n\n*Markdown is supported in descriptions. Add information here for users to get accustomed to endpoints*", "title": "Create Todo", "type": "http_operation" }, { "docs_url": "https://elements-examples.stoplight.io/docs/studio-demo/YXBpOjM4OTQzNA-to-dos", "id": "YXBpOjM4OTQzNA", "project_name": "Studio Demo", "slug": "YXBpOjM4OTQzNA-to-dos", "snippet": "![](https://i.ibb.co/v3Yt03v/todo-api-background.png) ## \ud83d\udcab Overview To Do API provides a simple way for people to manage their tasks and plan their day. This API can be used to create mobile and web applications.This API is documented using **Op...", "summary": "![](https://i.ibb.co/v3Yt03v/todo-api-background.png)\n\n## \ud83d\udcab Overview\n\nTo Do API provides a simple way for people to manage their tasks and plan their day. This API can be used to create mobile and web applications.This API is documented using **Op...", "title": "To-dos", "type": "http_service" } ], "total": 2, "truncated": false } ```