Skip to content

Write a version

OpenAPI JSON
POST
/v1/apps/{app}/versions
curl --request POST \
  --url https://api.eu.apigami.com/v1/apps/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/versions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "base_version_id": null, "changes": [ { "op": "write", "path": "manifest.json", "content": "{ \"openapi\": \"3.1.0\", … }" }, { "op": "write", "path": "main.ts", "content": "export default { fetch(request, env) { … } }" } ] }'

Three ways in. changes: files written, replaced or deleted on base_version_id, or on nothing when it is null, and the version is whole at once (200). archive: a deposit for a zip of the project, and file: a deposit for one file on a base; both answer 201 with upload.url, a one-shot address to PUT the bytes to, holding its own authorisation. A version whose manifest is wrong is kept, validation.status: "invalid" and diagnostics naming the file, the field and the fix. The smallest complete project: https://www.apigami.com/docs/build-an-application/#starter-template-hello-world-without-a-browser

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
app
required
string format: uuid

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
One of:
changes
object
mode
string
Allowed values: changes
base_version_id
required
string | null format: uuid
changes
required
Array
>= 1 items <= 100 items
One of:
object
op
required
string
Allowed values: write
path
required
string
<= 320 characters
content
required
string
encoding
string
default: utf-8
Allowed values: utf-8 base64
Example
{
  "base_version_id": null,
  "changes": [
    {
      "op": "write",
      "path": "manifest.json",
      "content": "{ \"openapi\": \"3.1.0\", … }"
    },
    {
      "op": "write",
      "path": "main.ts",
      "content": "export default { fetch(request, env) { … } }"
    }
  ]
}

Responses

Section titled “Responses”

200

Section titled “200”

The version, written from the changes.

Media typeapplication/json

Where one version stands. publish.next is the one sentence to act on.

object
version_id
required
string format: uuid
app_id
required
string format: uuid
base_version_id
string | null format: uuid
state
required

ready once written, deployed, pending_review, rejected, among others.

string
validation
required
object
status
string
Allowed values: valid invalid
errors
integer
diagnostics
Array<object>
object
code
required
string
file
required
string | null
pointer
required

A JSON pointer into the file.

string | null
message
required

The fix.

string
level

Present on a warning, which blocks nothing.

string
Allowed values: warning
version

The info.version of its manifest.

string | null
production
boolean
deployed
boolean
address

Where its pages answer, from the slug of its manifest.

object
production
string format: uri
staging
string format: uri
health
object
state
string | null
checked_at
string | null format: date-time
error
string | null
tried_at

When one of its actions first answered below 500 on its own deployment, which publication requires.

string | null format: date-time
publish
required
object
publishable
required
boolean
production
required
boolean
review_required
boolean
blockers
required
Array<object>
object
code
required
string
message
required
string
next
required
string
created_at
string format: date-time
published_at
string | null format: date-time
Example
{
  "validation": {
    "status": "valid",
    "diagnostics": [
      {
        "level": "warning"
      }
    ]
  }
}

201

Section titled “201”

A deposit reserved: the version exists once its bytes are PUT to upload.url.

Media typeapplication/json
object
version_id
required
string format: uuid
state
required
string
Allowed values: reserved
upload
required
object
url
required
string format: uri
method
required
string
Allowed values: PUT
headers
required
object
key
additional properties
string
expires_at
required
string format: date-time
Example
{
  "state": "reserved",
  "upload": {
    "method": "PUT"
  }
}

400

Section titled “400”

A change that cannot apply, such as a replace whose old_text appears zero times or more than once: nothing is written.

Media typeapplication/json
object
error
required
string
consentPending

Present and true when the approval window is open and the user has not answered within 45 s.

boolean
Example
{
  "error": "main.ts: `old_text` does not appear in this file. Nothing was written: correct this change and send them again."
}

404

Section titled “404”

Not an application of your team, or an unknown base version.

Media typeapplication/json
object
error
required
string
consentPending

Present and true when the approval window is open and the user has not answered within 45 s.

boolean
Example
{
  "error": "not found"
}