Val Town vals API
These endpoints let you get, create, and run vals.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/val-town-vals-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
OpenAPI Specification
openapi: 3.1.0
info:
title: Val Town alias vals API
description: 'Val Town’s public API
OpenAPI JSON endpoint:
https://api.val.town/openapi.json'
termsOfService: https://www.val.town/termsofuse
version: '1'
servers:
- url: https://api.val.town
description: Production
tags:
- name: vals
description: 'These endpoints
let you get, create, and run vals.'
paths:
/v2/vals/{val_id}:
get:
operationId: valsGet2
tags:
- vals
description: Get a val by id
parameters:
- schema:
type: string
format: uuid
in: path
name: val_id
required: true
description: Id of a val
responses:
'200':
description: A Val
content:
application/json:
schema:
$ref: '#/components/schemas/Val'
delete:
operationId: projectsDelete2
tags:
- vals
description: Delete a project
parameters:
- schema:
type: string
format: uuid
in: path
name: val_id
required: true
description: Id of a val
responses:
'204':
description: Default Response
'404':
description: Project not found
content:
application/json:
schema:
description: Project not found
/v2/vals:
get:
operationId: valsList2
tags:
- vals
description: Lists all vals including all public vals and your unlisted and private vals
parameters:
- schema:
enum:
- public
- unlisted
- private
in: query
name: privacy
required: false
description: This resource's privacy setting. Unlisted resources do not appear on profile pages or elsewhere, but you can link to them.
- schema:
type: string
format: uuid
in: query
name: user_id
required: false
description: User ID to filter by
- schema:
type: string
format: date-time
in: query
name: cursor
required: false
description: Cursor to start the pagination from
- schema:
type: integer
minimum: 1
maximum: 100
default: 20
in: query
name: limit
required: true
description: Maximum items to return in each paginated response
security:
- bearerAuth: []
responses:
'200':
description: A paginated result set
content:
application/json:
schema:
type: object
required:
- data
- links
properties:
data:
type: array
items:
$ref: '#/components/schemas/Val'
links:
$ref: '#/components/schemas/PaginationLinks'
description: A paginated result set
post:
operationId: valsCreate2
tags:
- vals
description: Create a new val
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
- privacy
properties:
name:
type: string
minLength: 1
maxLength: 48
pattern: ^[a-zA-Z][a-zA-Z0-9\-_]*$
description:
type: string
maxLength: 64
privacy:
enum:
- public
- unlisted
- private
orgId:
type: string
format: uuid
description: ID of the org to create the val in
description: Val information provided to create a new val
example:
name: myVal
description: My val
privacy: public
description: Val information provided to create a new val
responses:
'201':
description: A Val
content:
application/json:
schema:
$ref: '#/components/schemas/Val'
'409':
description: 'Conflict: Project name already exists'
content:
application/json:
schema:
description: 'Conflict: Project name already exists'
/v2/vals/{val_id}/branches/{branch_id}:
get:
operationId: branchesGet2
tags:
- vals
description: Get a branch by id
parameters:
- schema:
type: string
format: uuid
in: path
name: val_id
required: true
description: Id of a val
- schema:
type: string
format: uuid
in: path
name: branch_id
required: true
description: Id of a branch
responses:
'200':
description: A Branch
content:
application/json:
schema:
$ref: '#/components/schemas/Branch'
delete:
operationId: branchesDelete2
tags:
- vals
description: Delete a branch
parameters:
- schema:
type: string
format: uuid
in: path
name: val_id
required: true
description: Id of a val
- schema:
type: string
format: uuid
in: path
name: branch_id
required: true
description: Id of a branch
responses:
'204':
description: Deleted
'404':
description: Branch not found
content:
application/json:
schema:
description: Branch not found
/v2/vals/{val_id}/branches:
get:
operationId: branchesList2
tags:
- vals
description: List all branches for a val
parameters:
- schema:
type: integer
minimum: 0
default: 0
in: query
name: offset
required: true
description: Number of items to skip in order to deliver paginated results
- schema:
type: integer
minimum: 1
maximum: 100
default: 20
in: query
name: limit
required: true
description: Maximum items to return in each paginated response
- schema:
type: string
format: uuid
in: path
name: val_id
required: true
description: Id of a val
responses:
'200':
description: A paginated result set
content:
application/json:
schema:
type: object
required:
- data
- links
properties:
data:
type: array
items:
$ref: '#/components/schemas/Branch'
links:
$ref: '#/components/schemas/PaginationLinks'
description: A paginated result set
post:
operationId: branchesCreate2
tags:
- vals
description: Create a new branch
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- name
properties:
name:
type: string
minLength: 1
maxLength: 48
pattern: ^[a-zA-Z0-9\$\[\]\(\)\-_.]+$
branchId:
type: string
format: uuid
description: The branch ID to fork from. If this is not specified, the new branch will be forked from main.
description: Branch information provided to create a new project
example:
name: my-branch
branchId: 00000000-0000-0000-0000-000000000000
description: Branch information provided to create a new project
parameters:
- schema:
type: string
format: uuid
in: path
name: val_id
required: true
description: Id of a val
responses:
'201':
description: A Branch
content:
application/json:
schema:
$ref: '#/components/schemas/Branch'
'409':
description: 'Conflict: Branch name already exists in this project'
content:
application/json:
schema:
description: 'Conflict: Branch name already exists in this project'
/v2/vals/{val_id}/files:
get:
operationId: valFilesGet2
tags:
- vals
description: Get metadata for files and directories in a val. If path is an empty string, returns files at the root directory.
parameters:
- schema:
type: integer
minimum: 0
in: query
name: version
required: false
description: Specific branch version to query
- schema:
type: string
format: uuid
in: query
name: branch_id
required: false
description: Id to query
- schema:
type: string
in: query
name: path
required: true
description: Path to a file or directory (e.g. 'dir/subdir/file.ts'). Pass in an empty string to represent the root directory.
- schema:
type: boolean
default: false
in: query
name: recursive
required: true
description: Whether to recursively act on all files in the project
- schema:
type: integer
minimum: 0
default: 0
in: query
name: offset
required: true
description: Number of items to skip in order to deliver paginated results
- schema:
type: integer
minimum: 1
maximum: 100
default: 20
in: query
name: limit
required: true
description: Maximum items to return in each paginated response
- schema:
type: string
format: uuid
in: path
name: val_id
required: true
description: Id of a val
responses:
'200':
description: A paginated result set
content:
application/json:
schema:
type: object
required:
- data
- links
properties:
data:
type: array
items:
$ref: '#/components/schemas/FileRevisionMetadataV2'
links:
$ref: '#/components/schemas/PaginationLinks'
description: A paginated result set
post:
operationId: filesCreate2
tags:
- vals
description: Create a new file, project val or directory
requestBody:
required: true
content:
application/json:
schema:
anyOf:
- type: object
required:
- type
properties:
type:
type: string
enum:
- directory
content:
type: 'null'
- type: object
required:
- content
- type
properties:
content:
type: string
minLength: 0
maxLength: 80000
description: File and val content. An empty string will create an empty file. When creating a directory, the content should be null or undefined.
type:
enum:
- file
- interval
- http
- email
- script
parameters:
- schema:
type: string
format: uuid
in: query
name: branch_id
required: false
description: The specified branch of the resource. Defaults to main if not provided.
- schema:
type: string
in: query
name: path
required: true
description: Path to a file or directory (e.g. 'dir/subdir/file.ts'). Pass in an empty string to represent the root directory.
- schema:
type: string
format: uuid
in: path
name: val_id
required: true
description: Id of a val
responses:
'201':
description: A File or Directory's Metadata
content:
application/json:
schema:
$ref: '#/components/schemas/FileRevisionMetadataV2'
'409':
description: Default Response
content:
application/json:
schema:
type: object
required:
- message
properties:
message:
type: string
description: File or directory already exists at this path
delete:
operationId: filesDelete2
tags:
- vals
description: Deletes a file or a directory. To delete a directory and all of its children, use the recursive flag. To delete all files, pass in an empty path and the recursive flag.
parameters:
- schema:
type: string
format: uuid
in: query
name: branch_id
required: false
description: The specified branch of the resource. Defaults to main if not provided.
- schema:
type: string
in: query
name: path
required: true
description: Path to a file or directory (e.g. 'dir/subdir/file.ts'). Pass in an empty string to represent the root directory.
- schema:
type: boolean
default: false
in: query
name: recursive
required: true
description: Whether to recursively act on all files in the project
- schema:
type: string
format: uuid
in: path
name: val_id
required: true
description: Id of a val
responses:
'204':
description: Default Response
'404':
description: File not found
content:
application/json:
schema:
description: File not found
put:
operationId: fileContentUpdate2
tags:
- vals
description: Update a file's content
requestBody:
required: true
content:
application/json:
schema:
anyOf:
- type: object
properties:
content:
type: string
minLength: 0
maxLength: 80000
description: File and val content. An empty string will create an empty file. When creating a directory, the content should be null or undefined.
type:
enum:
- file
- interval
- http
- email
- script
parent_path:
anyOf:
- type: string
description: Path to the directory you'd like to move this file to (e.g. 'folder1/folder2')
- type: 'null'
name:
type: string
minLength: 1
maxLength: 48
pattern: ^[a-zA-Z0-9\$\[\]\(\)\-_.]+$
parameters:
- schema:
type: string
format: uuid
in: query
name: branch_id
required: false
description: The specified branch of the resource. Defaults to main if not provided.
- schema:
type: string
in: query
name: path
required: true
description: Path to a file or directory (e.g. 'dir/subdir/file.ts'). Pass in an empty string to represent the root directory.
- schema:
type: string
format: uuid
in: path
name: val_id
required: true
description: Id of a val
responses:
'200':
description: A File or Directory's Metadata
content:
application/json:
schema:
$ref: '#/components/schemas/FileRevisionMetadataV2'
'201':
description: A File or Directory's Metadata
content:
application/json:
schema:
$ref: '#/components/schemas/FileRevisionMetadataV2'
/v2/vals/{val_id}/environment_variables:
get:
operationId: valEnvironmentVariablesList
tags:
- vals
description: List environment variables defined in this project. This only includes names, not values.
parameters:
- schema:
type: integer
minimum: 0
default: 0
in: query
name: offset
required: true
description: Number of items to skip in order to deliver paginated results
- schema:
type: integer
minimum: 1
maximum: 100
default: 20
in: query
name: limit
required: true
description: Maximum items to return in each paginated response
- schema:
type: string
format: uuid
in: path
name: val_id
required: true
description: Id of a val
responses:
'200':
description: A paginated result set
content:
application/json:
schema:
type: object
required:
- data
- links
properties:
data:
type: array
items:
$ref: '#/components/schemas/TEnvironmentVariable'
links:
$ref: '#/components/schemas/PaginationLinks'
description: A paginated result set
post:
operationId: valEnvironmentVariablesCreate
tags:
- vals
description: Create a new environment variable scoped to this project.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- value
- key
properties:
value:
type: string
description: Value of the environment variable.
maxLength: 8192
description:
type: string
description: Optional description of the environment variable
maxLength: 1024
key:
type: string
maxLength: 8192
pattern: ^[A-Za-z_][A-Z0-9a-z_]*$
description: Name or key of the environment variable, accessible via Deno.env or process.env
description: Inputs for an environment variable
description: Inputs for an environment variable
parameters:
- schema:
type: string
format: uuid
in: path
name: val_id
required: true
description: Id of a val
responses:
'201':
description: An environment variable
content:
application/json:
schema:
$ref: '#/components/schemas/TEnvironmentVariable'
'409':
description: Key already exists
content:
application/json:
schema:
description: Key already exists
/v2/vals/{val_id}/environment_variables/{key}:
put:
operationId: valEnvironmentVariablesCreate
tags:
- vals
description: Update a environment variable scoped to this project.
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- value
properties:
value:
type: string
description: Value of the environment variable.
maxLength: 8192
description:
type: string
description: Optional description of the environment variable
maxLength: 1024
description: Inputs to update a environment variable
description: Inputs to update a environment variable
parameters:
- schema:
type: string
format: uuid
in: path
name: val_id
required: true
description: Id of a val
- schema:
type: string
in: path
name: key
required: true
responses:
'201':
description: An environment variable
content:
application/json:
schema:
$ref: '#/components/schemas/TEnvironmentVariable'
delete:
operationId: valEnvironmentVariablesDelete
tags:
- vals
description: Delete a environment variable scoped to this project.
parameters:
- schema:
type: string
format: uuid
in: path
name: val_id
required: true
description: Id of a val
- schema:
type: string
in: path
name: key
required: true
responses:
'204':
description: Default Response
'404':
description: Environment variable or project not found
content:
application/json:
schema:
description: Environment variable or project not found
/v2/vals/{val_id}/files/content:
get:
operationId: filesContentGet2
tags:
- vals
description: Download file content
parameters:
- schema:
type: integer
minimum: 0
in: query
name: version
required: false
description: Specific branch version to query
- schema:
type: string
format: uuid
in: query
name: branch_id
required: false
description: Id to query
- schema:
type: string
in: query
name: path
required: true
description: Path to a file or directory (e.g. 'dir/subdir/file.ts'). Pass in an empty string to represent the root directory.
- schema:
type: string
format: uuid
in: path
name: val_id
required: true
description: Id of a val
- schema:
type: string
in: header
name: If-Match
required: false
- schema:
type: string
in: header
name: If-Unmodified-Since
required: false
- schema:
type: string
in: header
name: If-None-Match
required: false
- schema:
type: string
in: header
name: If-Modified-Since
required: false
- schema:
type: string
in: header
name: Cache-Control
required: false
responses:
'200':
description: Contents of the file
content:
application/octet-stream:
schema:
type: string
format: string
'304':
description: Cached version of the file is the same as the one requested
content:
application/json:
schema:
description: Cached version of the file is the same as the one requested
'412':
description: Precondition failed
content:
application/json:
schema:
description: Precondition failed
type: string
components:
schemas:
FileRevisionMetadataV2:
type: object
required:
- name
- id
- path
- version
- updatedAt
- type
- links
properties:
name:
type: string
id:
type: string
format: uuid
description: The id of the resource
path:
type: string
version:
type: integer
minimum: 0
updatedAt:
type: string
format: date-time
type:
enum:
- directory
- file
- interval
- http
- email
- script
links:
type: object
required:
- self
- html
- module
properties:
self:
type: string
format: uri
description: The URL of this resource on this API
html:
type: string
format: uri
description: The URL of this resource on Val Town
module:
type: string
format: uri
description: The URL of this resource's source code as a module
endpoint:
type: string
format: uri
description: This resource's web endpoint, where it serves a website or API
email:
type: string
format: email
description: This resource's email address for receiving emails (for email-type vals)
description: A File or Directory's Metadata
Branch:
type: object
required:
- name
- id
- version
- createdAt
- updatedAt
- forkedBranchId
- links
properties:
name:
type: string
id:
type: string
format: uuid
description: The id of the branch
version:
type: integer
minimum: 0
createdAt:
type: string
format: date-time
updatedAt:
type: string
format: date-time
forkedBranchId:
anyOf:
- type: string
description: The id of the branch this branch was forked from
- type: 'null'
links:
type: object
required:
- self
- html
properties:
self:
type: string
format: uri
description: The URL of this resource on this API
html:
type: string
format: uri
description: The URL of this resource on Val Town
description: A Branch
TEnvironmentVariable:
type: object
required:
- key
- description
- updatedAt
- createdAt
properties:
key:
type: string
maxLength: 8192
pattern: ^[A-Za-z_][A-Z0-9a-z_]*$
description: Name or key of the environment variable, accessible via Deno.env or process.env
description:
anyOf:
- type: string
maxLength: 1024
description: Optional description of the environment variable
- type: 'null'
updatedAt:
anyOf:
- type: string
format: date-time
- type: 'null'
createdAt:
type: string
format: date-time
description: An environment variable
PaginationLinks:
type: object
required:
- self
properties:
self:
type: string
format: uri
description: URL of this page
prev:
type: string
format: uri
description: URL of the previous page, if any
next:
type: string
format: uri
description: URL of the next page, if any
description: Links to use for pagination
Val:
type: object
required:
- name
- id
- createdAt
- privacy
- author
- imageUrl
- description
- links
properties:
name:
type: string
id:
type: string
format: uuid
description: The id of the val
createdAt:
type: string
format: date-time
privacy:
enum:
- public
- unlisted
- private
description: This resource's privacy setting. Unlisted resources do not appear on profile pages or elsewhere, but you can link to them.
author:
type: object
required:
- type
- id
- username
properties:
type:
anyOf:
- type: string
enum:
- user
- type: string
enum:
- org
id:
type: string
format: uuid
username:
anyOf:
- type: string
- type: 'null'
imageUrl:
anyOf:
- type: string
description: The URL of this val's image
- type: 'null'
description:
anyOf:
- type: string
- type: 'null'
links:
type: object
required:
- self
- html
properties:
self:
type: string
format: uri
description: The URL of this resource on this API
html:
type: string
format: uri
description: The URL of this resource on Val Town
description: A Val
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: Endpoints that support authorization expect Bearer authentication, using an API token provided from Val Town.
externalDocs:
url: https://api.val.town/documentation
description: Find more info here