{"openapi":"3.1.0","info":{"title":"Val Town (BYOK) API","version":"0.1.0","description":"Val Town (BYOK) lets an AI assistant read your own Val Town data through the Val Town API with a key you supply (API token). Read-only: 10 tools (get_me, list_vals, list_my_vals, get_val, get_val_by_name, list_branches, list_files, list_blobs, list_organizations, list_logs). The BYOK key travels with each request, is used for that one call only and is never stored, logged or cached; it is only...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-valtown.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-valtown/docs"},"termsOfService":"https://connectorbay.com/byok-valtown/terms"},"servers":[{"url":"https://byok-valtown.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-valtown/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_me":{"post":{"operationId":"get_me","summary":"Show the Val Town account the token belongs to: id, type, username, bio, tier and profile URL. Use for \"Which Val Town a","description":"Show the Val Town account the token belongs to: id, type, username, bio, tier and profile URL. Use for \"Which Val Town account is my token for\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_meArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_vals":{"post":{"operationId":"list_vals","summary":"List vals visible to you (all public ones plus your own unlisted and private ones), optionally by privacy or owner, newe","description":"List vals visible to you (all public ones plus your own unlisted and private ones), optionally by privacy or owner, newest first. Use for \"Which vals do I have on Val Town\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"privacy":{"anyOf":[{"enum":["public","unlisted","private"],"type":"string"},{"type":"null"}],"default":null,"description":"Only vals with this privacy: public, unlisted or private.","title":"Privacy"},"user_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only vals owned by this user ID.","title":"User Id"},"cursor":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Pagination cursor from links.next of the previous answer.","title":"Cursor"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Maximum items to return (1 to 100, default 20).","title":"Limit"}},"title":"list_valsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_my_vals":{"post":{"operationId":"list_my_vals","summary":"List the vals owned by the token's account (beta endpoint), with offset paging. Use for \"List only my own Val Town vals\"","description":"List the vals owned by the token's account (beta endpoint), with offset paging. Use for \"List only my own Val Town vals\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of items to skip (default 0).","title":"Offset"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Maximum items to return (1 to 100, default 20).","title":"Limit"}},"title":"list_my_valsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_val":{"post":{"operationId":"get_val","summary":"Get one val's name, privacy, description, author and links. Use for \"Show details of a Val Town val\".","description":"Get one val's name, privacy, description, author and links. Use for \"Show details of a Val Town val\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"val_id":{"description":"The val's ID (a UUID), from list_vals or list_my_vals.","maxLength":200,"title":"Val Id","type":"string"}},"required":["val_id"],"title":"get_valArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_val_by_name":{"post":{"operationId":"get_val_by_name","summary":"Find a val by its owner's username and the val name. Use for \"Get alice's val called hello on Val Town\".","description":"Find a val by its owner's username and the val name. Use for \"Get alice's val called hello on Val Town\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"username":{"description":"Username of the val's owner.","maxLength":200,"title":"Username","type":"string"},"val_name":{"description":"Name of the val.","maxLength":200,"title":"Val Name","type":"string"}},"required":["username","val_name"],"title":"get_val_by_nameArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_branches":{"post":{"operationId":"list_branches","summary":"List a val's branches with version, creation and update time and the branch they were forked from. Use for \"What branche","description":"List a val's branches with version, creation and update time and the branch they were forked from. Use for \"What branches does this Val Town val have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"val_id":{"description":"The val's ID (a UUID), from list_vals or list_my_vals.","maxLength":200,"title":"Val Id","type":"string"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of items to skip (default 0).","title":"Offset"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Maximum items to return (1 to 100, default 20).","title":"Limit"}},"required":["val_id"],"title":"list_branchesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_files":{"post":{"operationId":"list_files","summary":"List files and directories of a val (metadata only: name, path, type, version, update time). Use for \"What files are in ","description":"List files and directories of a val (metadata only: name, path, type, version, update time). Use for \"What files are in this Val Town val\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"val_id":{"description":"The val's ID (a UUID), from list_vals or list_my_vals.","maxLength":200,"title":"Val Id","type":"string"},"path":{"description":"Directory or file path inside the val, for example 'src' or 'src/main.ts' (an empty root path cannot be sent by this connector).","maxLength":300,"title":"Path","type":"string"},"recursive":{"description":"True to list all files below the path.","title":"Recursive","type":"boolean"},"branch_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Branch ID to read (default: the main branch).","title":"Branch Id"},"version":{"anyOf":[{"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"A specific branch version number.","title":"Version"},"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of items to skip (default 0).","title":"Offset"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Maximum items to return (1 to 100, default 20).","title":"Limit"}},"required":["val_id","path","recursive"],"title":"list_filesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_blobs":{"post":{"operationId":"list_blobs","summary":"List the keys, sizes and last-modified times of your blob storage entries, optionally by key prefix. Use for \"What blobs","description":"List the keys, sizes and last-modified times of your blob storage entries, optionally by key prefix. Use for \"What blobs do I have stored in Val Town\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"prefix":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only keys that start with this text.","title":"Prefix"}},"title":"list_blobsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_organizations":{"post":{"operationId":"list_organizations","summary":"List the organizations you belong to. Use for \"Which Val Town organizations am I in\".","description":"List the organizations you belong to. Use for \"Which Val Town organizations am I in\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"offset":{"anyOf":[{"maximum":100000,"minimum":0,"type":"integer"},{"type":"null"}],"default":0,"description":"Number of items to skip (default 0).","title":"Offset"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Maximum items to return (1 to 100, default 20).","title":"Limit"}},"title":"list_organizationsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_logs":{"post":{"operationId":"list_logs","summary":"List recent OpenTelemetry log lines from your vals, newest first, optionally within a time window or for one file. Use f","description":"List recent OpenTelemetry log lines from your vals, newest first, optionally within a time window or for one file. Use for \"Show the latest logs from my Val Town vals\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"direction":{"description":"Sort order by time: desc (newest first, default) or asc.","enum":["asc","desc"],"title":"Direction","type":"string"},"start":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Earliest time to include, ISO 8601.","title":"Start"},"end":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Latest time to include, ISO 8601.","title":"End"},"file_id":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only logs from this file ID.","title":"File Id"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Maximum items to return (1 to 100, default 20).","title":"Limit"}},"required":["direction"],"title":"list_logsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}