{"openapi":"3.1.0","info":{"title":"BADM station editor API","version":"1.0.0","description":"Station metadata from the BADM triple store. Reading needs no token and answers from the final database: approved values only. An open read shows names and never a full e-mail address. The three membership calls need the station token and make a draft, as the editor does: the ETC admin approves or rejects it, and a rejection is mailed with its reason to who made the draft. There are no admin calls in this API."},"servers":[{"url":"/"}],"paths":{"/api/v1/stations":{"get":{"operationId":"listStations","summary":"The stations: id, name, country, latitude, longitude, IGBP class.","parameters":[],"responses":{"200":{"description":"The stations.","content":{"application/json":{"schema":{"type":"object","properties":{"stations":{"type":"array","items":{"$ref":"#/components/schemas/Station"}}}}}}}}}},"/api/v1/stations/{id}/people":{"get":{"operationId":"listPeople","summary":"The memberships of a station: person, role, institution, from and until. E-mail addresses are masked (an...@ex..org) unless the call carries the station's token.","parameters":[{"name":"id","in":"path","required":true,"description":"The station id, as BE-Bra.","schema":{"type":"string"}},{"name":"active","in":"query","required":false,"description":"true: only memberships that have not ended.","schema":{"type":"boolean"}}],"security":[{},{"stationToken":[]}],"responses":{"200":{"description":"The memberships of the station.","content":{"application/json":{"schema":{"type":"object","properties":{"station":{"type":"string"},"emails":{"type":"string","enum":["masked","full"]},"memberships":{"type":"array","items":{"$ref":"#/components/schemas/Membership"}}}}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"No such station."}}}},"/api/v1/stations/{id}/instruments":{"get":{"operationId":"listInstruments","summary":"The instruments of a station: model, type, serial number, current deployment.","parameters":[{"name":"id","in":"path","required":true,"description":"The station id, as BE-Bra.","schema":{"type":"string"}},{"name":"deployed","in":"query","required":false,"description":"true: only instruments deployed now.","schema":{"type":"boolean"}}],"responses":{"200":{"description":"The instruments of the station.","content":{"application/json":{"schema":{"type":"object","properties":{"station":{"type":"string"},"instruments":{"type":"array","items":{"$ref":"#/components/schemas/Instrument"}}}}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"No such station."}}}},"/api/v1/stations/{id}/export":{"get":{"operationId":"exportStation","summary":"The BADM data of a station as a workbook, as JSON or as Turtle: the final database, without pending drafts. E-mail addresses are masked (an...@ex..org) unless the call carries the station's token.","parameters":[{"name":"id","in":"path","required":true,"description":"The station id, as BE-Bra.","schema":{"type":"string"}},{"name":"format","in":"query","required":true,"description":"xlsx: a workbook in the layout of the BADM files; json: the same rows by group; ttl: the statements as Turtle.","schema":{"type":"string","enum":["xlsx","json","ttl"]}}],"security":[{},{"stationToken":[]}],"responses":{"200":{"description":"The station's data. The export says whether its addresses are masked or full.","content":{"application/vnd.openxmlformats-officedocument.spreadsheetml.sheet":{"schema":{"type":"string","format":"binary"}},"application/json":{"schema":{"type":"object"}},"text/turtle":{"schema":{"type":"string"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"No such station."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"A format that is not xlsx, json or ttl."}}}},"/api/v1/stations/{id}/changes":{"get":{"operationId":"listChanges","summary":"The change sets of a station with their status: what became of a draft.","parameters":[{"name":"id","in":"path","required":true,"description":"The station id, as BE-Bra.","schema":{"type":"string"}},{"name":"status","in":"query","required":false,"description":"Only the change sets of this status.","schema":{"type":"string","enum":["draft","stale","approved","rejected","withdrawn","superseded"]}}],"responses":{"200":{"description":"The change sets, newest first. E-mail addresses are masked.","content":{"application/json":{"schema":{"type":"object","properties":{"station":{"type":"string"},"changes":{"type":"array","items":{"$ref":"#/components/schemas/Change"}}}}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"No such station."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"A status that is none."}}}},"/api/v1/stations/{id}/memberships":{"post":{"operationId":"addMembership","summary":"Propose a person for the team of a station: a draft, which the ETC admin approves or rejects.","parameters":[{"name":"id","in":"path","required":true,"description":"The station id, as BE-Bra.","schema":{"type":"string"}}],"security":[{"stationToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MembershipNew"},"example":{"name":"Anna Berg","email":"anna.berg@example.org","role":"TEC","institution":"Example University","from":"2026-11-01","by":"Anna Berg","byEmail":"anna.berg@example.org"}}}},"responses":{"202":{"description":"Accepted as a draft. Nothing is changed until the ETC admin approves it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Draft"}}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"No station token, or one that is no station's."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The token of another station."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"No such station or membership."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"A value is not valid; error says which and why."}}}},"/api/v1/stations/{id}/memberships/{mid}":{"patch":{"operationId":"changeMembership","summary":"Propose a change of the role, institution, address or dates of a membership: a draft.","parameters":[{"name":"id","in":"path","required":true,"description":"The station id, as BE-Bra.","schema":{"type":"string"}},{"name":"mid","in":"path","required":true,"description":"The membership id, as the people call lists it.","schema":{"type":"string"}}],"security":[{"stationToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MembershipChange"},"example":{"role":"SCI","institution":"Example University","by":"Anna Berg"}}}},"responses":{"202":{"description":"Accepted as a draft. Nothing is changed until the ETC admin approves it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Draft"}}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"No station token, or one that is no station's."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The token of another station."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"No such station or membership."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"A value is not valid; error says which and why."}}}},"/api/v1/stations/{id}/memberships/{mid}/end":{"post":{"operationId":"endMembership","summary":"Propose the end of a membership with a date: a draft. Nothing is deleted.","parameters":[{"name":"id","in":"path","required":true,"description":"The station id, as BE-Bra.","schema":{"type":"string"}},{"name":"mid","in":"path","required":true,"description":"The membership id, as the people call lists it.","schema":{"type":"string"}}],"security":[{"stationToken":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MembershipEnd"},"example":{"until":"2026-12-31","by":"Anna Berg"}}}},"responses":{"202":{"description":"Accepted as a draft. Nothing is changed until the ETC admin approves it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Draft"}}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"No station token, or one that is no station's."},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"The token of another station."},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"No such station or membership."},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"description":"A value is not valid; error says which and why."}}}}},"components":{"securitySchemes":{"stationToken":{"type":"http","scheme":"bearer","description":"The station's token. In this play version it is the station's password."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"Station":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"country":{"type":"string","description":"The two letters the station id begins with."},"lat":{"type":["number","null"]},"long":{"type":["number","null"]},"igbp":{"type":"string"}}},"Membership":{"type":"object","properties":{"id":{"type":"string"},"person":{"type":"object","properties":{"name":{"type":"string"},"email":{"type":"string","description":"Masked, as an...@ex..org, unless the call carried the station token."}}},"role":{"type":"string"},"institution":{"type":"string"},"address":{"type":"string"},"from":{"type":"string"},"until":{"type":"string"},"active":{"type":"boolean"}}},"Instrument":{"type":"object","properties":{"id":{"type":"string"},"model":{"type":"string"},"type":{"type":"string","description":"What the model name has before its first hyphen: SA, GA_CP, TEMP ..."},"serial_number":{"type":"string"},"deployed":{"type":"boolean"},"deployment":{"type":["object","null"],"properties":{"since":{"type":"string"},"height":{"type":["number","null"]},"eastward":{"type":["number","null"]},"northward":{"type":["number","null"]},"variables":{"type":"array","items":{"type":"string"}}}}}},"MembershipNew":{"type":"object","required":["name","role","by"],"properties":{"name":{"type":"string"},"email":{"type":"string"},"role":{"type":"string","description":"A value of the list TEAM_ROLE: PI, CO-PI, MANAGER, SCI, TEC, DATA ..."},"institution":{"type":"string"},"address":{"type":"string"},"from":{"type":"string","description":"YYYY-MM-DD"},"by":{"type":"string","description":"Who makes the change. It goes on the change set. A member of the team, by name; if not, give byEmail."},"byEmail":{"type":"string","description":"Where a rejection is sent when by is no member of the team."}}},"MembershipChange":{"type":"object","required":["by"],"properties":{"role":{"type":"string"},"institution":{"type":["string","null"]},"address":{"type":["string","null"]},"from":{"type":["string","null"]},"until":{"type":["string","null"]},"by":{"type":"string"},"byEmail":{"type":"string"}}},"Draft":{"type":"object","properties":{"change":{"type":"string","description":"The change set of the draft."},"status":{"type":"string"},"membership":{"type":"string"},"note":{"type":"string"}}},"Change":{"type":"object","properties":{"id":{"type":"string"},"station":{"type":"string"},"when":{"type":"string"},"who":{"type":"string"},"action":{"type":"string"},"about":{"type":"string"},"status":{"type":"string","enum":["draft","stale","approved","rejected","withdrawn","superseded"]},"reason":{"type":"string","description":"Why it was rejected."},"decidedBy":{"type":"string"},"decidedAt":{"type":"string"},"changes":{"type":"array","items":{"type":"object","properties":{"k":{"type":"string","description":"removed or added"},"s":{"type":"string"},"p":{"type":"string"},"o":{"type":"array"}}}}}},"MembershipEnd":{"type":"object","required":["until","by"],"properties":{"until":{"type":"string","description":"YYYY-MM-DD"},"by":{"type":"string"},"byEmail":{"type":"string"}}}}}}