{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/derive-to/json-schema/derive-to-artifact-schema.json",
  "title": "Artifact",
  "x-generated": "2026-11-05",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/derive-to-openapi.json#/components/schemas/Artifact",
  "type": "object",
  "properties": {
    "short_id": {
      "type": "string",
      "description": "Stable public id — the /a/<short_id> URL slug."
    },
    "url": {
      "type": "string",
      "description": "Canonical public URL of the artifact."
    },
    "title": {
      "type": [
        "string",
        "null"
      ],
      "description": "Display title; null when untitled or taken down."
    },
    "kind": {
      "type": "string",
      "enum": [
        "file",
        "bundle"
      ],
      "description": "file = single file; bundle = multi-file archive (skill, site, or docs folder)."
    },
    "current_content_type": {
      "type": [
        "string",
        "null"
      ],
      "description": "MIME type of the current version's content."
    },
    "locked": {
      "type": "boolean",
      "description": "When true, direct publishes are blocked — changes go through review."
    },
    "import_source": {
      "type": [
        "string",
        "null"
      ],
      "description": "`arxiv` when Derive fetched this content rather than someone authoring it here. Such a paper is read as it renders: its source is for agents, so the viewer offers no file list, source download, bibliography editor or diff."
    },
    "workspace_access": {
      "type": "string",
      "enum": [
        "none",
        "member"
      ],
      "description": "v2 access: member = workspace seats reach it at their role; none = they don't."
    },
    "link_role": {
      "type": "string",
      "enum": [
        "none",
        "viewer",
        "commenter",
        "editor"
      ],
      "description": "v2 access: what merely holding the world link confers (none = no link)."
    },
    "listed": {
      "type": "string",
      "enum": [
        "none",
        "workspace",
        "public"
      ],
      "description": "v2 access: where it surfaces for discovery — nowhere, the workspace, or public."
    },
    "password_protected": {
      "type": "boolean",
      "description": "true when the world link is password-locked (the password is never returned)."
    },
    "badge": {
      "type": "boolean",
      "description": "Show the Made-with-Derive mark on this artifact's public surfaces (false = white-label workspace)."
    },
    "open_comment_count": {
      "type": "number",
      "description": "Open-thread count for the sign-in-to-comment pill; present only for anonymous callers on a link that grants commenting."
    },
    "public_history": {
      "type": "boolean",
      "description": "Owner opt-in: readers without artifact standing can browse version history. When false, their detail responses carry only the current version."
    },
    "is_workspace_member": {
      "type": "boolean",
      "description": "True when the signed-in caller has an active seat in the artifact's workspace. False for link-only readers and members acting in another workspace."
    },
    "org_id": {
      "type": "string",
      "description": "The artifact's workspace id; drives move-to-workspace."
    },
    "raw_token": {
      "type": "string",
      "description": "Signed, short-lived token for fetching raw content; detail responses only."
    },
    "raw_token_expires_at": {
      "type": "string",
      "description": "Expiry of raw_token as an ISO timestamp; detail responses only."
    },
    "spa": {
      "type": "boolean",
      "description": "true when the bundle is a single-page app (all paths route to the entry)."
    },
    "current_version": {
      "type": "number",
      "description": "Latest version number; 0 before any content is published."
    },
    "versions": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "n": {
            "type": "number"
          },
          "content_type": {
            "type": "string",
            "description": "MIME type of this version's content."
          },
          "author": {
            "type": "string",
            "description": "Display byline; heals to the author's current name."
          },
          "author_login": {
            "type": [
              "string",
              "null"
            ],
            "description": "Committer's GitHub login; null when not a GitHub commit."
          },
          "author_avatar": {
            "type": [
              "string",
              "null"
            ]
          },
          "author_gh_id": {
            "type": [
              "string",
              "null"
            ],
            "description": "Committer's GitHub user id; null when not a GitHub commit."
          },
          "handle": {
            "type": [
              "string",
              "null"
            ],
            "description": "Committer's Derive @handle; null unless they signed in with GitHub."
          },
          "agent": {
            "type": [
              "object",
              "null"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              }
            },
            "required": [
              "id",
              "name"
            ],
            "description": "The agent that produced this version on the author's behalf; null for the person's own publish."
          },
          "message": {
            "type": [
              "string",
              "null"
            ],
            "description": "Version (commit) message; null when none given."
          },
          "name": {
            "type": [
              "string",
              "null"
            ],
            "description": "Optional version label; null when unnamed."
          },
          "created_at": {
            "type": "string"
          }
        },
        "required": [
          "n",
          "author",
          "message",
          "name",
          "created_at"
        ]
      }
    },
    "sessions": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/VersionSession"
      },
      "description": "Versions grouped into time-clustered sessions for the UI (newest-first)."
    },
    "views": {
      "type": "number",
      "description": "Total views; present only when analytics is enabled."
    },
    "my_role": {
      "type": [
        "string",
        "null"
      ],
      "enum": [
        "viewer",
        "commenter",
        "editor",
        "owner",
        null
      ],
      "description": "The caller's effective permission tier; null when they have none."
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "favorite": {
      "type": "boolean",
      "description": "true when the caller has favorited this."
    },
    "has_preview": {
      "type": "boolean",
      "description": "true when the current version has a ready screenshot preview."
    },
    "open_threads": {
      "type": "number",
      "description": "Count of open (unresolved) comment threads."
    },
    "mentions_me": {
      "type": "boolean",
      "description": "true when an open thread @mentions the calling user."
    },
    "i_participated": {
      "type": "boolean",
      "description": "true when the caller authored or commented in a thread here."
    },
    "collections": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Ids of the collections that include this artifact."
    },
    "collection_access": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/CollectionGrant"
      },
      "description": "Collections whose sharing ADDS reach to this artifact — the share dialog's disclosure rows, renderable verbatim (the caller's own solo invite-only collection is already excluded). Detail responses only; scoped to collections the caller can see, except the artifact's managers (explicit or seat standing — never mere link-holders), who see every granting collection."
    },
    "removed": {
      "type": "boolean",
      "description": "true when the artifact has been taken down (tombstone)."
    },
    "archived": {
      "type": "boolean",
      "description": "true when the artifact is on the reversible archive shelf."
    },
    "bundle": {
      "type": "object",
      "properties": {
        "isSkill": {
          "type": "boolean",
          "description": "true when the bundle is a skill (entry SKILL.md)."
        },
        "name": {
          "type": [
            "string",
            "null"
          ],
          "description": "Skill/bundle name; null when not declared."
        },
        "description": {
          "type": [
            "string",
            "null"
          ],
          "description": "Skill/bundle description; null when not declared."
        },
        "entry": {
          "type": "string",
          "description": "Path of the entry document rendered first."
        },
        "files": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "path": {
                "type": "string"
              },
              "type": {
                "type": "string"
              }
            },
            "required": [
              "path",
              "type"
            ]
          },
          "description": "The bundle's file tree (path + MIME type) for navigation."
        }
      },
      "required": [
        "isSkill",
        "name",
        "description",
        "entry",
        "files"
      ],
      "description": "Present for a markdown bundle (skill or docs folder): entry, file tree, identity."
    },
    "linked_bundle": {
      "type": "object",
      "properties": {
        "schema": {
          "type": "string",
          "enum": [
            "derive.linked-bundle/v1"
          ]
        },
        "purpose": {
          "type": "string"
        },
        "members": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "ref": {
                "type": "string"
              },
              "label": {
                "type": "string"
              },
              "role": {
                "type": "string"
              },
              "note": {
                "type": "string"
              },
              "available": {
                "type": "boolean"
              },
              "url": {
                "type": "string"
              },
              "title": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "content_type": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "current_version": {
                "type": "integer",
                "minimum": 0,
                "exclusiveMinimum": true
              },
              "updated_at": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "open_comment_count": {
                "type": "integer",
                "minimum": 0
              }
            },
            "required": [
              "id",
              "ref",
              "label",
              "available"
            ]
          }
        },
        "diagrams": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "title": {
                "type": "string"
              },
              "type": {
                "type": "string",
                "enum": [
                  "loop",
                  "graph"
                ]
              },
              "tier": {
                "type": "string",
                "enum": [
                  "utility",
                  "fast",
                  "balanced",
                  "expert",
                  "frontier"
                ],
                "description": "Default capability tier for nodes without their own tier."
              },
              "nodes": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "label": {
                      "type": "string"
                    },
                    "member": {
                      "type": "string"
                    },
                    "role": {
                      "type": "string",
                      "description": "The responsibility this node owns."
                    },
                    "tier": {
                      "type": "string",
                      "enum": [
                        "utility",
                        "fast",
                        "balanced",
                        "expert",
                        "frontier"
                      ],
                      "description": "Node capability tier; overrides the diagram default."
                    },
                    "state": {
                      "type": "string",
                      "enum": [
                        "pending",
                        "active",
                        "waiting",
                        "blocked",
                        "done"
                      ]
                    },
                    "basis_version": {
                      "type": "integer",
                      "minimum": 0,
                      "exclusiveMinimum": true
                    },
                    "note": {
                      "type": "string"
                    },
                    "confidence": {
                      "type": "object",
                      "properties": {
                        "level": {
                          "type": "string",
                          "enum": [
                            "low",
                            "medium",
                            "high"
                          ]
                        },
                        "basis": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "level",
                        "basis"
                      ],
                      "description": "Current confidence and the evidence or judgment supporting it."
                    },
                    "help": {
                      "type": "object",
                      "properties": {
                        "needed": {
                          "type": "boolean"
                        },
                        "question": {
                          "type": "string"
                        },
                        "can_continue": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "needed"
                      ],
                      "description": "Whether help is needed, the concise question, and work that can continue."
                    }
                  },
                  "required": [
                    "id",
                    "label"
                  ]
                }
              },
              "edges": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "from": {
                      "type": "string"
                    },
                    "to": {
                      "type": "string"
                    },
                    "label": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "from",
                    "to"
                  ]
                }
              },
              "goal": {
                "type": "string"
              },
              "evaluate": {
                "type": "string"
              },
              "stop": {
                "type": "string"
              }
            },
            "required": [
              "id",
              "title",
              "type",
              "nodes",
              "edges"
            ]
          }
        }
      },
      "required": [
        "schema",
        "purpose",
        "members"
      ],
      "description": "Present for an HTML artifact carrying a valid bundle-manifest fact. Members are resolved through the caller's normal read permissions; unavailable members expose no additional metadata."
    },
    "workflow_preview": {
      "$ref": "#/$defs/WorkflowPreview"
    },
    "derived_from": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "short_id": {
          "type": "string"
        },
        "title": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "required": [
        "short_id",
        "title"
      ],
      "description": "The artifact this one was copied from (\"use as template\"). Detail responses only; null when the source no longer resolves, absent when not derived."
    },
    "created_at": {
      "type": "string"
    },
    "updated_at": {
      "type": [
        "string",
        "null"
      ],
      "description": "Last-update timestamp; null when never updated since creation."
    },
    "author_name": {
      "type": [
        "string",
        "null"
      ],
      "description": "Raw current-author name; the resolved `author` object is preferred."
    },
    "author_login": {
      "type": [
        "string",
        "null"
      ],
      "description": "Raw current-author GitHub login; null when not from GitHub."
    },
    "author_avatar": {
      "type": [
        "string",
        "null"
      ],
      "description": "Raw current-author avatar URL; null when none."
    },
    "author_gh_id": {
      "type": [
        "string",
        "null"
      ],
      "description": "Raw current-author GitHub id; null when not from GitHub."
    },
    "author": {
      "type": [
        "object",
        "null"
      ],
      "properties": {
        "name": {
          "type": [
            "string",
            "null"
          ]
        },
        "login": {
          "type": [
            "string",
            "null"
          ],
          "description": "GitHub login; null if never signed in with GitHub."
        },
        "avatar": {
          "type": [
            "string",
            "null"
          ]
        },
        "handle": {
          "type": [
            "string",
            "null"
          ],
          "description": "Derive @handle; null when the author has none."
        }
      },
      "required": [
        "name",
        "login",
        "avatar",
        "handle"
      ],
      "description": "Resolved current-author profile; preferred over the raw author_* fields."
    }
  },
  "required": [
    "short_id",
    "url",
    "title",
    "kind",
    "current_version",
    "versions"
  ],
  "$defs": {
    "CollectionGrant": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "title": {
          "type": "string"
        },
        "workspace_access": {
          "type": "string",
          "enum": [
            "none",
            "member"
          ],
          "description": "\"member\" = every workspace seat opens the artifact at their role."
        },
        "my_role": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "viewer",
            "commenter",
            "editor",
            "owner",
            null
          ],
          "description": "Caller's role on the COLLECTION (owner ⇒ can manage its sharing); null if none."
        },
        "member_count": {
          "type": "number",
          "description": "Explicit collection-member rows (the creator always holds one)."
        },
        "created_by": {
          "type": "string",
          "description": "Creator's user id — permanently owner of the collection."
        },
        "owner_name": {
          "type": [
            "string",
            "null"
          ],
          "description": "Creator's display name for attribution (\"Managed by …\"); null when unknown."
        }
      },
      "required": [
        "id",
        "title",
        "workspace_access",
        "my_role",
        "member_count",
        "created_by",
        "owner_name"
      ]
    },
    "VersionSession": {
      "type": "object",
      "properties": {
        "n": {
          "type": "number",
          "description": "Newest version number in this grouped session."
        },
        "from_n": {
          "type": "number",
          "description": "Oldest version number in this grouped session."
        },
        "count": {
          "type": "number",
          "description": "How many versions this session groups."
        },
        "author": {
          "type": "string"
        },
        "agent_name": {
          "type": [
            "string",
            "null"
          ],
          "description": "The agent that produced the session on the author's behalf; null for the person's own edits."
        },
        "name": {
          "type": [
            "string",
            "null"
          ],
          "description": "Session label; null when unnamed."
        },
        "created_at": {
          "type": "string",
          "description": "Timestamp of the newest version in the group."
        }
      },
      "required": [
        "n",
        "from_n",
        "count",
        "author",
        "agent_name",
        "name",
        "created_at"
      ]
    },
    "WorkflowPreview": {
      "type": "object",
      "properties": {
        "status": {
          "type": "string",
          "enum": [
            "ready",
            "needs-changes"
          ]
        },
        "execution_started": {
          "type": "boolean",
          "enum": [
            false
          ]
        },
        "purpose": {
          "type": [
            "string",
            "null"
          ]
        },
        "errors": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "warnings": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "diagrams": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "title": {
                "type": "string"
              },
              "will_do": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "may_do": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "will_pause": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "can_repeat": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "side_effects": {
                "type": "array",
                "items": {
                  "type": "string"
                }
              },
              "node_details": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "node_id": {
                      "type": "string"
                    },
                    "instruction": {
                      "type": [
                        "string",
                        "null"
                      ]
                    },
                    "result": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  },
                  "required": [
                    "node_id",
                    "instruction",
                    "result"
                  ]
                }
              },
              "context_sessions": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "node_id": {
                      "type": "string"
                    },
                    "label": {
                      "type": "string"
                    },
                    "context_ref": {
                      "type": "string"
                    },
                    "result": {
                      "type": "string"
                    },
                    "starts_when": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "node_id",
                    "label",
                    "context_ref",
                    "result",
                    "starts_when"
                  ]
                },
                "description": "The steps that ask an agent (`kind: \"context\"` nodes): the agent each names in `context_ref`, the result it should return, and when it starts."
              },
              "scenarios": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "kind": {
                      "type": "string",
                      "enum": [
                        "expected",
                        "failure",
                        "human"
                      ]
                    },
                    "outcome": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "kind",
                    "outcome"
                  ]
                }
              }
            },
            "required": [
              "id",
              "title",
              "will_do",
              "may_do",
              "will_pause",
              "can_repeat",
              "side_effects",
              "node_details",
              "context_sessions",
              "scenarios"
            ]
          }
        },
        "cannot_do": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      },
      "required": [
        "status",
        "execution_started",
        "purpose",
        "errors",
        "warnings",
        "diagrams",
        "cannot_do"
      ],
      "description": "Present when the current linked bundle also carries workflow-definition. This is the validated, non-executing shared Preview."
    }
  }
}