# publishes.create

> POST https://app.intraface.cc/api/v1/boards/{id}/publishes

An agent token (`Authorization: Bearer ifc_…`) or a signed-in person. Needs the `board.publish` permission on the board. Body limit: 4096 KB.

**Auth:** agent token (`Authorization: Bearer ifc_…`) or signed-in session (`__session` cookie)

## Path parameters

- `id` (string, required)

## Request body (application/json)

```json
{
  "type": "object",
  "properties": {
    "base_n": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "manifest": {
      "type": "object",
      "properties": {
        "entry": {
          "type": "string",
          "pattern": "\\.html?$"
        },
        "files": {}
      },
      "required": [
        "entry",
        "files"
      ]
    },
    "refs": {
      "maxItems": 10000,
      "type": "array",
      "items": {
        "type": "string",
        "maxLength": 2048
      }
    },
    "message": {
      "type": "string",
      "minLength": 1,
      "maxLength": 500
    },
    "agent": {
      "type": "string",
      "minLength": 1,
      "maxLength": 64
    },
    "resolves": {
      "maxItems": 50,
      "type": "array",
      "items": {
        "type": "string",
        "format": "uuid",
        "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
      }
    },
    "idempotency_key": {
      "type": "string",
      "minLength": 16,
      "maxLength": 128
    }
  },
  "required": [
    "base_n",
    "manifest",
    "refs",
    "message",
    "agent",
    "idempotency_key"
  ]
}
```

## Responses

### 200: Already done: an idempotent replay or a no-op.

application/json:

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "board_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "author_id": {
      "type": "string",
      "pattern": "^user_[A-Za-z0-9]+$"
    },
    "agent": {
      "type": "string"
    },
    "base_n": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "message": {
      "type": "string"
    },
    "state": {
      "type": "string",
      "enum": [
        "proposed",
        "published",
        "needs_rebase",
        "rejected"
      ]
    },
    "result_n": {
      "anyOf": [
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ]
    },
    "error": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "code": {
              "type": "string",
              "enum": [
                "bad_request",
                "unauthorized",
                "forbidden",
                "not_found",
                "conflict",
                "needs_rebase",
                "too_large",
                "missing_blob",
                "missing_asset",
                "external_media",
                "bad_manifest",
                "too_many_new_blobs",
                "bad_base",
                "rate_limited",
                "retry",
                "not_implemented",
                "upgrade_required",
                "unsupported_media_type",
                "authorization_pending",
                "slow_down",
                "expired_token",
                "access_denied",
                "taken_down",
                "blocked_content",
                "internal"
              ]
            },
            "message": {
              "type": "string"
            },
            "hint": {
              "type": "string"
            },
            "details": {}
          },
          "required": [
            "code",
            "message"
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
    }
  },
  "required": [
    "id",
    "board_id",
    "author_id",
    "agent",
    "base_n",
    "message",
    "state",
    "result_n",
    "error",
    "created_at"
  ]
}
```

### 201: Success.

application/json:

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "board_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "author_id": {
      "type": "string",
      "pattern": "^user_[A-Za-z0-9]+$"
    },
    "agent": {
      "type": "string"
    },
    "base_n": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "message": {
      "type": "string"
    },
    "state": {
      "type": "string",
      "enum": [
        "proposed",
        "published",
        "needs_rebase",
        "rejected"
      ]
    },
    "result_n": {
      "anyOf": [
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ]
    },
    "error": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "code": {
              "type": "string",
              "enum": [
                "bad_request",
                "unauthorized",
                "forbidden",
                "not_found",
                "conflict",
                "needs_rebase",
                "too_large",
                "missing_blob",
                "missing_asset",
                "external_media",
                "bad_manifest",
                "too_many_new_blobs",
                "bad_base",
                "rate_limited",
                "retry",
                "not_implemented",
                "upgrade_required",
                "unsupported_media_type",
                "authorization_pending",
                "slow_down",
                "expired_token",
                "access_denied",
                "taken_down",
                "blocked_content",
                "internal"
              ]
            },
            "message": {
              "type": "string"
            },
            "hint": {
              "type": "string"
            },
            "details": {}
          },
          "required": [
            "code",
            "message"
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
    }
  },
  "required": [
    "id",
    "board_id",
    "author_id",
    "agent",
    "base_n",
    "message",
    "state",
    "result_n",
    "error",
    "created_at"
  ]
}
```

### 202: Accepted: waiting for approval.

application/json:

```json
{
  "type": "object",
  "properties": {
    "id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "board_id": {
      "type": "string",
      "format": "uuid",
      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
    },
    "author_id": {
      "type": "string",
      "pattern": "^user_[A-Za-z0-9]+$"
    },
    "agent": {
      "type": "string"
    },
    "base_n": {
      "type": "integer",
      "minimum": 0,
      "maximum": 9007199254740991
    },
    "message": {
      "type": "string"
    },
    "state": {
      "type": "string",
      "enum": [
        "proposed",
        "published",
        "needs_rebase",
        "rejected"
      ]
    },
    "result_n": {
      "anyOf": [
        {
          "type": "integer",
          "exclusiveMinimum": 0,
          "maximum": 9007199254740991
        },
        {
          "type": "null"
        }
      ]
    },
    "error": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "code": {
              "type": "string",
              "enum": [
                "bad_request",
                "unauthorized",
                "forbidden",
                "not_found",
                "conflict",
                "needs_rebase",
                "too_large",
                "missing_blob",
                "missing_asset",
                "external_media",
                "bad_manifest",
                "too_many_new_blobs",
                "bad_base",
                "rate_limited",
                "retry",
                "not_implemented",
                "upgrade_required",
                "unsupported_media_type",
                "authorization_pending",
                "slow_down",
                "expired_token",
                "access_denied",
                "taken_down",
                "blocked_content",
                "internal"
              ]
            },
            "message": {
              "type": "string"
            },
            "hint": {
              "type": "string"
            },
            "details": {}
          },
          "required": [
            "code",
            "message"
          ]
        },
        {
          "type": "null"
        }
      ]
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
    }
  },
  "required": [
    "id",
    "board_id",
    "author_id",
    "agent",
    "base_n",
    "message",
    "state",
    "result_n",
    "error",
    "created_at"
  ]
}
```

### 409: `needs_rebase`

application/json:

```json
{
  "allOf": [
    {
      "$ref": "#/components/schemas/ApiError"
    },
    {
      "type": "object",
      "properties": {
        "error": {
          "type": "object",
          "properties": {
            "details": {
              "type": "object",
              "properties": {
                "head_n": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 9007199254740991
                },
                "paths": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "theirs_by": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "properties": {
                      "n": {
                        "type": "integer",
                        "exclusiveMinimum": 0,
                        "maximum": 9007199254740991
                      },
                      "who": {
                        "type": "string"
                      },
                      "agent": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "n",
                      "who",
                      "agent"
                    ]
                  }
                }
              },
              "required": [
                "head_n",
                "paths",
                "theirs_by"
              ]
            }
          }
        }
      }
    }
  ]
}
```

### default

Any other error, in the shared envelope `{ error: { code, message, hint?, details? } }`.
