Skip to content

Commit dbdca1f

Browse files
DogmaDragonDogmaDragon
committed
Refactor Stash API documentation for clarity and accuracy
1 parent 6f9d88e commit dbdca1f

File tree

1 file changed

+22
-147
lines changed

1 file changed

+22
-147
lines changed

‎docs/api.md‎

Lines changed: 22 additions & 147 deletions
Original file line numberDiff line numberDiff line change
@@ -4,168 +4,43 @@ hide:
44
- navigation
55
---
66

7-
There is a GraphQL API which allows to do things automatically. GraphQL is also self-documenting.
7+
# Stash API
88

9-
Stash has integrated playground where you run interact with the API and view the documentation.
9+
The Stash GraphQL API facilitates automated operations through a type-based schema that is both introspective and self-documenting.
1010

11-
1. Go to `<server>:<port>/playground` (default is `http://localhost:9999/playground`).
12-
1. Expand **Docs** on the right to open Documentation Explorer.
11+
Stash includes an integrated playground where users can execute queries and retrieve schema structures and documentation via a special introspection query.
1312

14-
All HTTP requests have to go to `<server>:<port>/graphql` (default is `http://localhost:9999/graphql`).
13+
1. You can access the playground by navigating to `<server>:<port>/playground` (default: [http://localhost:9999/playground](http://localhost:9999/playground){target="_blank"}).
14+
2. Click <svg height="1em" viewBox="0 0 20 24" fill="none" xmlns="http://www.w3.org/2000/svg"><path d="M0.75 3C0.75 4.24264 1.75736 5.25 3 5.25H17.25M0.75 3C0.75 1.75736 1.75736 0.75 3 0.75H16.25C16.8023 0.75 17.25 1.19772 17.25 1.75V5.25M0.75 3V21C0.75 22.2426 1.75736 23.25 3 23.25H18.25C18.8023 23.25 19.25 22.8023 19.25 22.25V6.25C19.25 5.69771 18.8023 5.25 18.25 5.25H17.25" stroke="currentColor" stroke-width="1.5"></path><line x1="13" y1="11.75" x2="6" y2="11.75" stroke="currentColor" stroke-width="1.5"></line></svg> on the left to access the Documentation Explorer.
1515

16-
## Authentication
17-
18-
You just need to add the key you generated in Stash (for more info about the API Key check stash's help section) in a header for every request you make.
19-
20-
=== "Example using curl"
21-
22-
```shell
23-
curl -X POST -H "ApiKey: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1aWQiOiJiaWxsIiwiaWF0IjoxNjE3MDkzMDYwLCJzdWIiOiJBUElLZXkifQ.WhUyvmnVeW8wGV5fkVyje3xLfz5A97HFwyZy-4i8Q-I" -H "Content-Type: application/json" --data '{ "query": "mutation { metadataScan (input:{})}" }' localhost:9999/graphql
24-
```
25-
26-
### Legacy cookie authentication
27-
28-
If you have configured a username/password you have to use cookies to authenticate.
29-
30-
=== "Example using curl"
31-
32-
```shell
33-
curl --verbose --cookie-jar cookie.txt --data 'username=stash&password=**' localhost:9998/login
34-
curl --cookie cookie.txt -H "Content-Type: application/json" --data '{ "query": "mutation { metadataScan ( input: {} ) } "}' localhost:9999/graphql
35-
```
36-
37-
Using the `API Key` is recommended instead of the above cookie method.
38-
39-
## Scan for new files
40-
41-
=== "`HTTP-POST`"
42-
43-
```json
44-
{
45-
"query": "mutation { metadataScan ( input: {} ) }"
46-
}
47-
```
48-
49-
=== "Example using curl"
50-
51-
```shell
52-
curl -X POST -H "Content-Type: application/json" --data '{ "query": " mutation { metadataScan (input: {} ) }" }' localhost:9999/graphql
53-
```
54-
55-
56-
57-
## Create backup
58-
59-
=== "`HTTP-POST`"
60-
61-
```json
62-
{
63-
"query": "mutation { backupDatabase(input: {download: false})}"
64-
}
65-
```
66-
67-
=== "Example using curl"
68-
69-
```shell
70-
curl -X POST -H "Content-Type: application/json" --data '{ "query": "mutation {backupDatabase(input: {download: false})}" }' localhost:9999/graphql
71-
```
72-
73-
If `download:` is `true` the created backup is returned and not stored locally.
16+
All HTTP requests should be directed to `<server>:<port>/graphql` (default: `http://localhost:9999/graphql`).
7417

75-
## Generate content
18+
!!! tip
19+
For further information, visit the [official GraphQL site](https://graphql.org/learn/){target="_blank"}.
7620

77-
=== "`HTTP-POST`"
78-
79-
Payload (set desired content to generate **covers**, **sprites**, **previews**, **imagePreviews**, **markers**, **transcodes**, **phashes**, **interactiveHeatmapsSpeeds**, **imageThumbnails**, **clipPreviews** to `true` or `false`.
80-
81-
```json
82-
{
83-
"query": "mutation { metadataGenerate ( input : { sprites: true previews: false imagePreviews: false markers: false transcodes: false } ) }"
84-
}
85-
```
86-
87-
=== "Example using curl"
88-
89-
```shell
90-
curl -X POST -H "Content-Type: application/json" --data '{ "query": "mutation { metadataGenerate ( input : { sprites: false previews: true imagePreviews: false markers: false transcodes: false } ) }" }' localhost:9999/graphql
91-
```
92-
93-
## Get studios
94-
95-
=== "`HTTP-POST`"
96-
97-
Payload (must be at least one of `id` `checksum` `url` `name` `image_path` `scene_count`).
98-
99-
```json
100-
{
101-
"query": "{ allStudios { id checksum url name image_path scene_count } }"
102-
}
103-
```
104-
105-
=== "Example using curl"
106-
107-
```shell
108-
curl -X POST -H "Content-Type: application/json" --data '{ "query": "{ allStudios { name url scene_count} }" }' localhost:9999/graphql
109-
```
110-
111-
## Scrape perfomer attributes from Freeones
112-
113-
=== "`HTTP-POST`"
114-
115-
Payload
116-
117-
- `$performer name` is the name of the Performer you are scraping for
118-
- return values must be at least one of `name` `url` `twitter` `instagram` `birthdate` `ethnicity` `country` `eye_color` `height` `measurements` `fake_tits` `career_length` `tattoos` `piercings` `aliases`
119-
120-
```json
121-
{
122-
"query": "{ scrapeFreeones(performer_name: $performer_name) { name url twitter instagram birthdate ethnicity country eye_color height measurements fake_tits career_length tattoos piercings aliases } }"
123-
}
124-
```
125-
126-
1. Caution is needed when used in a script. Always set a waiting/sleep period between calls to avoid getting blacklisted by Freeones.
127-
1. Due to way it's used in Stash and to work reliably it requires the prior use of **scrapeFreeonesPerfomerList** (described beneath) to make sure the name of the performer exists in the list returned and thus in the Freeones db.
21+
## Authentication
12822

23+
Include the API key generated in Stash in the header of every request. For details on obtaining the API Key, refer to Stash's in-app manual.
12924

13025
=== "Example using curl"
13126

132-
```shell
133-
curl -X POST -H "Content-Type: application/json" --data '{ "query": "{ scrapeFreeones ( performer_name : \"Abella Danger\" ) { name height birthdate} }" }' localhost:9999/graphql
134-
```
135-
136-
## Get list of perfomer names that match a name or alias from Freeones
27+
Replace `<your_api_key>` with your **API Key** found under :fontawesome-solid-gear: **Settings** > **Security** > **Authentication**.
13728

138-
=== "`HTTP-POST`"
29+
Replace `<graphql_query>` with the raw query, which can be formatted using the playground.
13930

140-
Payload (`$q` is the name or alias (or partial name , alias) of the performer you are looking for).
31+
```shell
32+
curl -X POST -H "ApiKey: <your_api_key>" -H "Content-Type: application/json" --data '{ "query": "<graphql_query>" }' localhost:9999/graphql
33+
```
14134

142-
```json
143-
{
144-
"query": "{ scrapeFreeonesPerformerList(query: $q) }"
145-
}
146-
```
35+
### Legacy cookie authentication
14736

148-
1. Caution is needed when used in a script.Always set a waiting/sleep period between calls to avoid getting blacklisted by Freeones
37+
For configurations using a username/password, cookies must be used for authentication.
14938

15039
=== "Example using curl"
15140

41+
```shell
42+
curl --verbose --cookie-jar cookie.txt --data 'username=stash&password=**' localhost:9999/login
43+
curl --cookie cookie.txt -H "Content-Type: application/json" --data '{ "query": "<graphql_query>" }' localhost:9999/graphql
44+
```
15245

153-
```shell
154-
curl -X POST -H "Content-Type: application/json" --data '{ "query": "{ scrapeFreeonesPerformerList (query: \"bella\" ) }" }' localhost:9999/graphql
155-
```
156-
157-
## Get system status
158-
159-
=== "`HTTP-POST`"
160-
161-
```json
162-
{
163-
"query": "{ systemStatus { databaseSchema databasePath configPath appSchema status } }"
164-
}
165-
```
166-
167-
=== "Example using curl"
168-
169-
```shell
170-
curl -X POST -H "Content-Type: application/json" --data '{ "query": "{ systemStatus { appSchema status } }" }' localhost:9999/graphql
171-
```
46+
It is recommended to use the `API Key` method over the legacy cookie method.

0 commit comments

Comments
 (0)