openapi: 3.0.3 info: title: TriplyDB Accounts Stories API version: 26.5.104 description: "REST API for TriplyDB — a linked data database platform.\n\n## Authentication\n\nRead operations on publicly published datasets can be performed without\nauthentication. Write operations and read operations on private or internal\ndatasets require a valid API token.\n\n### Creating an API token\n\n1. Log into your TriplyDB instance.\n2. Click on the user menu in the top-right corner and click on \"User settings\".\n3. Go to the \"API tokens\" tab.\n4. Click \"Create token\", enter a description (e.g., \"my-script\") and select\n the appropriate access rights.\n5. Click \"Create\" and copy the token. It is only shown once upon creation.\n\n### Using the API token\n\nInclude the token in the `Authorization` header of your HTTP requests:\n\n```\nAuthorization: Bearer YOUR_TOKEN\n```\n\n### Security considerations\n\n- **Do not commit tokens to git repositories.**\n- **Do not share tokens** with anyone who should not have access to your\n TriplyDB resources.\n- **Rotate tokens regularly**, especially if you suspect a compromise.\n\n## Pagination\n\nList endpoints are paginated. The response includes a `Link` header\n([RFC 8288](https://www.rfc-editor.org/rfc/rfc8288)) with URLs for\nnavigating the result set. To paginate, follow the URLs in the `Link`\nheader rather than constructing URLs manually.\n\nThe `Link` header contains up to three relations:\n\n| Relation | Meaning |\n|----------|---------|\n| `first` | URL to the first page of results |\n| `next` | URL to the next page (absent when on the last page) |\n| `prev` | URL to the previous page (absent when on the first page) |\n\nExample response header:\n\n```\nLink: ; rel=\"first\",\n ; rel=\"next\"\n```\n\nTo iterate through all results, keep following the `rel=\"next\"` URL until\nit is no longer present. You can control the page size with the `limit`\nquery parameter (default: 30).\n\n## Content negotiation\n\nLinked data endpoints support format negotiation in two ways:\n\n1. **Accept header** — set the `Accept` request header to the desired media type.\n2. **URL extension** — append a format extension to the URL path (e.g., `/run.csv`).\n When present, the extension takes precedence over the `Accept` header.\n" contact: name: Triply url: https://triply.cc servers: - url: https://api.lod.uba.uva.nl description: This instance security: - bearerAuth: [] - {} tags: - name: Stories description: Data stories paths: /stories: get: tags: - Stories summary: List all stories operationId: listAllStories security: - {} parameters: - name: q in: query schema: type: string - $ref: '#/components/parameters/since' - $ref: '#/components/parameters/limit' - $ref: '#/components/parameters/sortDirection' responses: '200': description: Paginated story list headers: Link: $ref: '#/components/headers/Link' content: application/json: schema: type: array items: $ref: '#/components/schemas/Story' /stories/{account}: parameters: - $ref: '#/components/parameters/account' get: tags: - Stories summary: List stories for an account operationId: listAccountStories security: - {} parameters: - $ref: '#/components/parameters/since' - name: sortBy in: query schema: type: string enum: - name - $ref: '#/components/parameters/sortDirection' responses: '200': description: Stories for the account headers: Link: $ref: '#/components/headers/Link' content: application/json: schema: type: array items: $ref: '#/components/schemas/Story' post: tags: - Stories summary: Create a story operationId: createStory requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/StoryCreate' responses: '201': description: Story created content: application/json: schema: $ref: '#/components/schemas/Story' '401': $ref: '#/components/responses/Unauthorized' /stories/{account}/{story}: parameters: - $ref: '#/components/parameters/account' - $ref: '#/components/parameters/story' get: tags: - Stories summary: Get a story operationId: getStory security: - {} responses: '200': description: Story details content: application/json: schema: $ref: '#/components/schemas/Story' '404': $ref: '#/components/responses/NotFound' patch: tags: - Stories summary: Update a story operationId: updateStory requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/StoryUpdate' responses: '200': description: Updated story content: application/json: schema: $ref: '#/components/schemas/Story' '401': $ref: '#/components/responses/Unauthorized' delete: tags: - Stories summary: Delete a story operationId: deleteStory responses: '204': description: Story deleted '401': $ref: '#/components/responses/Unauthorized' /stories/{account}/{story}/copy: parameters: - $ref: '#/components/parameters/account' - $ref: '#/components/parameters/story' post: tags: - Stories summary: Copy a story operationId: copyStory requestBody: required: true content: application/json: schema: type: object required: - toAccount properties: toAccount: type: string responses: '201': description: Copied story content: application/json: schema: $ref: '#/components/schemas/Story' '401': $ref: '#/components/responses/Unauthorized' /stories/{account}/{story}/chown: parameters: - $ref: '#/components/parameters/account' - $ref: '#/components/parameters/story' post: tags: - Stories summary: Transfer story ownership operationId: chownStory requestBody: required: true content: application/json: schema: type: object required: - toAccount properties: toAccount: type: string responses: '200': description: Story with new owner content: application/json: schema: $ref: '#/components/schemas/Story' '401': $ref: '#/components/responses/Unauthorized' /stories/{account}/{story}/banner.webp: parameters: - $ref: '#/components/parameters/account' - $ref: '#/components/parameters/story' post: tags: - Stories summary: Upload story banner image operationId: uploadStoryBanner requestBody: content: multipart/form-data: schema: type: object properties: banner: type: string format: binary responses: '200': description: Updated story content: application/json: schema: $ref: '#/components/schemas/Story' '401': $ref: '#/components/responses/Unauthorized' /stories/{account}/{story}/banner: parameters: - $ref: '#/components/parameters/account' - $ref: '#/components/parameters/story' get: tags: - Stories summary: Get story banner image operationId: getStoryBanner security: - {} parameters: - name: v in: query description: Version schema: type: string - name: w in: query description: Width schema: type: integer - name: h in: query description: Height schema: type: integer responses: '200': description: Banner image content: image/webp: schema: type: string format: binary image/png: schema: type: string format: binary components: schemas: AccessLevel: type: string enum: - public - private - internal Dataset: type: object required: - id - name - displayName - description - owner - accessLevel - createdAt - updatedAt - graphCount - statements - serviceCount - assetCount - tags - prefixes - exampleResources - hasDataQualityIssues - toggles properties: id: type: string readOnly: true example: 64a1b2c3d4e5f60012345678 name: type: string example: knowledge-graph displayName: type: string example: Knowledge Graph description: type: string example: An enterprise knowledge graph linking people, projects, and publications. avatarUrl: type: string readOnly: true owner: readOnly: true allOf: - $ref: '#/components/schemas/Account' accessLevel: $ref: '#/components/schemas/AccessLevel' license: $ref: '#/components/schemas/DatasetLicenseId' createdAt: type: string format: date-time readOnly: true example: 2024-03-01 12:00:00+00:00 updatedAt: type: string format: date-time readOnly: true graphCount: type: integer readOnly: true example: 3 statements: type: integer readOnly: true example: 1250000 lastGraphsUpdateTime: type: string format: date-time readOnly: true serviceCount: type: integer readOnly: true example: 1 assetCount: type: integer readOnly: true example: 0 tags: type: array items: type: string example: - linked-data - knowledge-graph prefixes: $ref: '#/components/schemas/Prefixes' exampleResources: type: array items: type: string hasDataQualityIssues: type: boolean readOnly: true autogeneratedIdType: $ref: '#/components/schemas/AutoGeneratedIdType' toggles: $ref: '#/components/schemas/DatasetToggles' DatasetToggles: type: object properties: browserUi: type: boolean tableUi: type: boolean dataEditorUi: type: boolean dataModelEditorUi: type: boolean insightsUi: type: boolean sparqlIdeUi: type: boolean graphqlUi: type: boolean elasticsearchUi: type: boolean graphsUi: type: boolean servicesUi: type: boolean assetsUi: type: boolean SparqlRequestType: type: string enum: - select - construct - ask - describe - update StoryElementHeight: type: string enum: - small - medium - large Story: type: object required: - id - name - owner - accessLevel - link - content - createdAt - updatedAt properties: id: type: string readOnly: true example: 64a1b2c3d4e5f60012345680 name: type: string example: dataset-overview displayName: type: string example: Dataset Overview owner: readOnly: true allOf: - $ref: '#/components/schemas/Account' accessLevel: $ref: '#/components/schemas/AccessLevel' link: type: string readOnly: true content: type: array items: $ref: '#/components/schemas/StoryElement' createdAt: type: string format: date-time readOnly: true updatedAt: type: string format: date-time readOnly: true bannerUrl: type: string readOnly: true tags: type: array items: type: string example: - data-story - overview StoryElement: type: object discriminator: propertyName: type required: - id - type properties: id: type: string readOnly: true type: type: string enum: - query - paragraph description: '`query` — embeds a saved SPARQL query visualisation. `paragraph` — free-form Markdown text block. ' query: $ref: '#/components/schemas/Query' queryVersion: type: integer caption: type: string width: $ref: '#/components/schemas/StoryElementWidth' height: $ref: '#/components/schemas/StoryElementHeight' paragraph: type: string DatasetLicenseId: type: string nullable: true enum: - CC0 1.0 - CC BY - CC BY-ND - CC BY-NC - CC BY-NC-ND - CC BY-NC-SA - CC BY-SA v4.0 - ODC-By - ODC-ODbL - PDDL - GFDL - CC-BY-SA - null QueryExecutionStatus: type: string enum: - No versions - No dataset - Parsing error - Warning - No suitable service - Service error - Timeout - No results - Success - No information Account: type: object discriminator: propertyName: type mapping: user: '#/components/schemas/User' org: '#/components/schemas/Org' required: - accountName - uid - createdAt - description - type properties: accountName: type: string example: acme-research uid: type: string readOnly: true example: 64a1b2c3d4e5f60012345678 name: type: string example: ACME Research Lab description: type: string example: Publishing linked open data for the sciences. avatarUrl: type: string readOnly: true createdAt: type: string format: date-time readOnly: true example: 2024-01-15 10:30:00+00:00 updatedAt: type: string format: date-time readOnly: true type: $ref: '#/components/schemas/AccountType' accountType: type: string enum: - user - group readOnly: true pinnedItems: type: array items: type: object datasetCount: type: integer readOnly: true queryCount: type: integer readOnly: true storyCount: type: integer readOnly: true email: type: string format: email AutoGeneratedIdType: type: string enum: - uuid - hex8 - hex10 StoryUpdate: type: object properties: name: type: string displayName: type: string accessLevel: $ref: '#/components/schemas/AccessLevel' content: type: array items: $ref: '#/components/schemas/StoryElementUpdate' tags: type: array items: type: string VersionInformation: type: object readOnly: true properties: version: type: integer example: 1 accountName: type: string name: type: string avatar: type: string createdAt: type: string format: date-time QueryRequestConfig: type: object properties: payload: type: object properties: query: type: string example: SELECT ?class (COUNT(?s) AS ?count) WHERE { ?s a ?class } GROUP BY ?class ORDER BY DESC(?count) LIMIT 10 update: type: string headers: type: object additionalProperties: type: string ldFrame: type: object type: $ref: '#/components/schemas/SparqlRequestType' valid: type: boolean readOnly: true ErrorResponse: type: object required: - message properties: message: type: string example: Resource not found. code: type: integer example: 404 errors: type: array items: $ref: '#/components/schemas/ErrorResponse' QueryExecutionStatistics: type: object required: - status properties: executedAt: type: string format: date-time executionTimeInMs: type: number resultCount: type: integer status: $ref: '#/components/schemas/QueryExecutionStatus' errorMessage: type: string Prefixes: type: object additionalProperties: type: string format: uri example: rdf: http://www.w3.org/1999/02/22-rdf-syntax-ns# rdfs: http://www.w3.org/2000/01/rdf-schema# AccountType: type: string enum: - user - org QueryRenderConfig: type: object properties: output: type: string settings: type: object Query: type: object required: - id - name - description - owner - accessLevel - service - serviceConfig - tags - link - version - numberOfVersions - createdAt - updatedAt properties: id: type: string readOnly: true example: 64a1b2c3d4e5f6001234567f name: type: string example: top-10-classes displayName: type: string example: Top 10 Classes description: type: string example: Returns the 10 most frequently used RDF classes. owner: readOnly: true allOf: - $ref: '#/components/schemas/Account' accessLevel: $ref: '#/components/schemas/AccessLevel' dataset: $ref: '#/components/schemas/Dataset' service: type: string readOnly: true serviceConfig: type: object properties: type: type: string enum: - speedy - virtuoso - jena - blazegraph service: type: object properties: id: type: string name: type: string type: type: string tags: type: array items: type: string example: - sparql - classes link: type: string readOnly: true version: type: integer readOnly: true example: 1 versionsInformation: type: array readOnly: true items: $ref: '#/components/schemas/VersionInformation' numberOfVersions: type: integer readOnly: true example: 1 requestConfig: $ref: '#/components/schemas/QueryRequestConfig' renderConfig: $ref: '#/components/schemas/QueryRenderConfig' createdAt: type: string format: date-time readOnly: true updatedAt: type: string format: date-time readOnly: true variables: type: array items: $ref: '#/components/schemas/VariableConfig' lastQueriedAt: type: string format: date-time readOnly: true executionStats: readOnly: true allOf: - $ref: '#/components/schemas/QueryExecutionStatistics' StoryElementUpdate: type: object required: - type properties: id: type: string type: type: string enum: - query - paragraph query: type: string queryVersion: type: integer paragraph: type: string caption: type: string width: $ref: '#/components/schemas/StoryElementWidth' height: $ref: '#/components/schemas/StoryElementHeight' StoryElementWidth: type: string enum: - fullWidth - default VariableConfig: type: object required: - name - termType properties: name: type: string example: class defaultValue: type: string example: http://schema.org/Person required: type: boolean allowedValues: type: array items: type: string termType: type: string enum: - NamedNode - Literal example: NamedNode datatype: type: string language: type: string StoryCreate: type: object required: - name properties: name: type: string displayName: type: string accessLevel: $ref: '#/components/schemas/AccessLevel' content: type: array items: $ref: '#/components/schemas/StoryElementUpdate' tags: type: array items: type: string parameters: sortDirection: name: sortDirection in: query description: Sort direction schema: type: string enum: - asc - desc limit: name: limit in: query description: Maximum number of results schema: type: integer minimum: 1 account: name: account in: path required: true description: Account name (user or group) schema: type: string story: name: story in: path required: true description: Story name schema: type: string since: name: since in: query description: Cursor for pagination. Should be provided using the `link` header schema: type: string responses: Unauthorized: description: Authentication required content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' NotFound: description: Resource not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' headers: Link: description: 'RFC 8288 pagination links. Contains `rel="first"` and `rel="next"` URIs for cursor-based pagination. ' schema: type: string example: ; rel="first", ; rel="next" securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT